diff --git a/docs/roadmap/commandkit-migration-discussion.md b/docs/roadmap/commandkit-migration-discussion.md index a8f1da84..65532fa7 100644 --- a/docs/roadmap/commandkit-migration-discussion.md +++ b/docs/roadmap/commandkit-migration-discussion.md @@ -2,49 +2,29 @@ ## Purpose And Status -Working notepad for the CommandKit decisions that will be incorporated into the -[master PromptKit-native migration roadmap](promptkit.md). Record the proposal, -open questions, evidence, and decisions here as we discuss them. +Discussion record for the decisions incorporated into the +[master native migration roadmap](promptkit.md). That roadmap now owns the +selected design, remaining choices, implementation phases, removal inventory, +and acceptance criteria. This notepad retains discussion detail and evidence; +it is not a second implementation checklist. -**Direction agreed:** Make a full cutover to a CommandKit-native application as -part of the same migration as modern PromptKit, in separate, reviewable -implementation steps. Adopt CommandKit's public-facing conventions and -recommendations to the fullest extent. Bring its design decisions forward and -complete adoption before the overall cutover. +**Direction agreed and incorporated:** Make a full cutover to native CommandKit, +ConfigKit, and PromptKit workflows in one coordinated migration. Adopt upstream +public conventions fully. CLI backward compatibility is a non-goal; provide +release migration guidance instead. -The master roadmap currently places CommandKit in a subsequent Phase 7 and leaves -its details in U10. That sequencing has not yet been revised. Item 6 selects how -to incorporate the agreed decisions into its dependency baseline, implementation -phases, removal inventory, and acceptance criteria while preserving remaining -choices explicitly. No application or dependency changes have been implemented -through this discussion. +All six items below are incorporated, including the accepted-artifact cache, +small completion report and native text template, debug inventory/depth, +`/tmp/notarius-debug` default, `latest`, and explicit-empty directory behavior. +No application or dependency changes have been implemented through this +planning work. Implementation remains pending. -Item 1 selects the dependency versions and standard capabilities, including -PromptKit v0.23.3 in place of the master roadmap's initial v0.23.2 target. -Item 2 selects the application command structure and input conventions. Item 3 -selects native composition, shared loaders, and application preflight. Item 4 -selects artifact-first output, a small native completion report, and outcomes. -Item 5 selects conditional debug capture through the shared `--debug` flag, -native diagnostics, and a run/operation bundle with a `latest` symlink. Its -capture inventory, depth, and -explicit-empty directory behavior are resolved below. Item 6 selects verification, -migration guidance, and incorporation into the master roadmap; that incorporation -is still pending. - -The cache follow-up in item 4 replaces the earlier checkpoint design with an -accepted-artifact cache keyed by initial message content. The output/report -direction is settled: deliver artifacts as files and render a small structured -completion value through CommandKit, with a native text template for ordinary -human output. Detailed diagnostics belong in optional debug capture. Function -signatures, debug filenames other than `latest`, and similar implementation -details do not reopen the selected architecture. Broader PromptKit choices -remain with the master roadmap. - -The PromptKit ownership direction remains in force. The revised -[cache decision](promptkit-architecture-discussion.md#5-accepted-artifact-cache) -supersedes earlier checkpoint matching and provenance requirements. Master-roadmap -incorporation is pending, including U1 (the upstream content-hash capability), -U8 (cache migration), U9 (records/reporting), and U10 (CommandKit adoption). +The roadmap resolves U10's CommandKit scope, tracks the pending upstream +message-content hash in U1, replaces U8's checkpoint design, and narrows U9 to +implementation details within the agreed output/debug contracts. Schema handling, +role-specific correction/fallback policy, worker defaults, and concrete cache +controls/transition remain visible there. Item-level directions below record the +accepted design; the roadmap is the authority for sequencing and current status. ## Agreed Proposal @@ -129,8 +109,8 @@ Two application needs already identified for deliberate treatment are: 4. Complete command and reporting migration before final end-to-end verification and migration documentation. -Item 6 selects the replacement phase sequence for incorporation into the master -roadmap. The master roadmap has not yet been updated. +Item 6 records the incorporation decision. The master roadmap now owns the +resulting six-phase sequence; implementation is pending. ## 1. Adoption Scope And Dependency Baseline @@ -201,11 +181,10 @@ The standard capability suite needs no identified upstream addition. The later cache decision does require a native message-content hash, which is not the existing v0.23.3 rendered-prompt hash. Confirm the supplying API/release before implementing cache lookup; the version table remains the reviewed baseline, not -a claim that the new hash is already available. On roadmap -reconciliation, incorporate these versions into U1, replace U10's open standard -capability selection with this decision, and incorporate the application wiring -and presentation decisions from items 2–5. Retire superseded durable-record -requirements as directed by item 6. +a claim that the new hash is already available. The master roadmap now records +this baseline, the pending upstream requirement, the resolved CommandKit scope, +and the application wiring/presentation decisions. Superseded durable-record +requirements have been removed from that plan. ## 2. Native Command Surface And Inputs @@ -352,8 +331,8 @@ Application handlers still validate meaningful input combinations and translate typed inputs into pipeline selections. Native `--debug` supplies reporting behavior and conditional artifact capture as selected in item 5. Items 3–4 select loader behavior, the small completion report, and native outcome -presentation. Reconcile U9 with these decisions rather than expanding durable -metadata. +presentation. The master roadmap limits U9 to implementation details within +these decisions. Evidence: [CommandKit command/input conventions](../../../commandkit/docs/cli.md#registered-command-syntax), [reusable PromptKit flags](../../../commandkit/docs/consumers/guide.md#request-builders-and-loading), @@ -570,7 +549,7 @@ model execution or a claim of validation under a changed policy. Concrete cache flags and legacy-checkpoint handling remain implementation-planning choices. The output/report discussion must not reintroduce cache metadata solely -to populate a report. The master roadmap still needs this replacement policy. +to populate a report. The master roadmap now incorporates this replacement policy. ### Artifacts Are The Deliverable @@ -760,8 +739,8 @@ The current [run-result contract](../integrations/run-result.md) and [CLI failure mapping](../internal/cli.md#failure-mapping-and-terminal-reporting) document migration impact. Item 6 of the [PromptKit discussion record](promptkit-architecture-discussion.md#6-inspection-and-execution-bookkeeping) -retains the native bookkeeping boundary. Reconcile U9 with this simpler contract, -including retirement of superseded durable-record requirements. +retains the native bookkeeping boundary. The master roadmap now incorporates +this contract and retires superseded durable-record requirements. ## 5. Debug Capture And Optional Diagnostics @@ -1137,8 +1116,8 @@ The current [debug lifecycle](../internal/state.md#debug-bundles) and **Discussion / decision:** Agreed. Complete one coordinated native cutover, with CommandKit composition introduced early, verification focused on Notarius's integration and domain responsibilities, and practical release migration guidance. -Incorporate these decisions into the existing master roadmap; another replacement -document is unnecessary. Implementation and master-roadmap incorporation are pending. +These decisions are incorporated into the existing master roadmap; no replacement +document was needed. Implementation is pending. ### Focused Verification Of Application Behavior @@ -1225,39 +1204,22 @@ Keep future behavior in roadmap documents until implemented. ### Incorporation Into The Master Roadmap -Replace the deferred CommandKit Phase 7 with adoption throughout the existing -master roadmap. Use this phase sequence: +**Completed:** The [master roadmap](promptkit.md#implementation-sequence) now +integrates CommandKit throughout six phases, beginning with native composition +and shared loaders, proving a representative pipeline through the new CLI, and +finishing cache/output/capture integration before final verification. The old +separate Phase 7 is retired. -1. Establish the agreed dependency baseline and remaining contract decisions. -2. Build native application composition, shared loaders, standard commands, and - the dedicated preflight package alongside native source assembly. -3. Prove a representative native pipeline through the actual command surface, - including reporting and useful debug capture. -4. Migrate remaining roles and remove the adapter, scheduler, retry machinery, - and custom CLI infrastructure. -5. Complete cache migration, the selected output/report contract, and capture behavior. -6. Verify the assembled application and finish migration documentation. +Its dependency baseline includes the selected versions and pending upstream hash +request. U10 is resolved; U8 now concerns cache operation/transition, and U9 +concerns implementation details within the selected output/debug contracts. +Earlier receipt/manifest inventories are retired. Remaining schema, correction, +fallback, worker, and cache-transition choices are explicit in its +[unresolved-choice table](promptkit.md#unresolved-choices). -Each phase delivers a reviewable result with appropriate verification. Tests and -documentation proceed throughout; the final phase checks integration and -completeness. The phases do not require separate releases or an intermediate -compatibility framework. - -Resolve U1's dependency baseline and U10's CommandKit scope from items 1–4. Narrow -U9 to item 4's selected artifact-first output/completion contract and item 5's -debug implementation details within the resolved inventory, depth, and controls. -Retire earlier receipt/manifest field inventories rather than treating them as -unresolved requirements to recreate. -Update U1 for the upstream message-content hash and replace U8's checkpoint -identity/provenance plan with the accepted-artifact cache decision. -Reconcile removal inventory and acceptance criteria, including old -inspection-command and machine-output compatibility assumptions. Preserve -unresolved schema handling, role-specific retry/fallback policy, worker defaults, -checkpoint transition choices, and other concrete choices until actually settled. - -Once incorporated, the master roadmap owns implementation sequencing and status; -both migration notepads remain discussion records. Do not maintain competing -implementation checklists in the notepads. +The master roadmap owns sequencing and implementation status. This notepad and +the PromptKit discussion remain discussion records, not competing implementation +checklists. ### Completion Checks diff --git a/docs/roadmap/promptkit-architecture-discussion.md b/docs/roadmap/promptkit-architecture-discussion.md index d0418978..2fa31888 100644 --- a/docs/roadmap/promptkit-architecture-discussion.md +++ b/docs/roadmap/promptkit-architecture-discussion.md @@ -2,20 +2,17 @@ ## Purpose And Status -The original decisions in items 1–6 were incorporated into the -[PromptKit-native architecture migration roadmap](promptkit.md). That roadmap -is the implementation plan and owns current unresolved choices, sequencing, -acceptance criteria, and implementation status. +The decisions in items 1–6, the subsequent CommandKit discussion, and the +simplified cache/output designs are incorporated into the +[master native migration roadmap](promptkit.md). It owns the selected target, +unresolved choices, sequencing, acceptance criteria, and implementation status. -The subsequent CommandKit discussion replaces item 5's checkpoint proposal with -the accepted-artifact cache below and clarifies PromptKit's execution ownership. -Those updates have not yet been incorporated into the master roadmap. They -supersede its earlier checkpoint matching and provenance requirements. The -[CommandKit notepad](commandkit-migration-discussion.md) records the related CLI -and debug decisions. Its [item 4](commandkit-migration-discussion.md#4-reports-machine-output-and-outcomes) -selects artifact files and a small native completion report, superseding earlier -mandatory manifest, receipt, and durable-execution-record proposals here and in -the master roadmap. +The [CommandKit discussion record](commandkit-migration-discussion.md) retains +the related CLI, preflight, output, debug, and migration rationale. The master +roadmap replaces earlier checkpoint matching/provenance proposals with the +accepted-artifact cache and retires mandatory manifests, extensive receipts, +and durable execution ledgers. The upstream message-content hash remains pending; +incorporation does not claim it is already available or implemented. This document retains the discussion, rationale, and evidence, including item 7's completed Audita comparison. Item-level questions and follow-ups below record @@ -475,7 +472,7 @@ This is a concrete upstream hash requirement. The reviewed PromptKit v0.23.3 hashing the entire `PreparedRun` would include volatile execution metadata. Neither is the selected key. Expose the content hash through native preparation rather than implementing another message-hashing policy in Notarius. Confirm -the supplying upstream API/release during roadmap incorporation; do not claim +the supplying upstream API/release before cache implementation; do not claim the proposed field already exists or silently substitute a broader fingerprint. ### Compute Early, Store After Acceptance @@ -548,10 +545,10 @@ compatibility requirement. Select straightforward cache reuse/bypass/refresh controls and legacy-file handling during implementation planning; do not infer new flag spellings or a migration framework from this decision. -**Follow-up:** Incorporate this design and the upstream hash requirement into the -master roadmap. Verify that a downstream failure leaves earlier accepted -artifacts reusable, corrected answers are stored under the initial hash, changed -messages miss, settings-only changes can hit, and a hit makes no model calls or +**Follow-up:** The master roadmap now includes this design and the upstream hash +requirement. During implementation, verify that a downstream failure leaves +earlier accepted artifacts reusable, corrected answers are stored under the +initial hash, changed messages miss, settings-only changes can hit, and a hit makes no model calls or new semantic-validation claims. Keep output/report contract decisions separate. ## 6. Inspection And Execution Bookkeeping @@ -670,7 +667,7 @@ Evidence: [current inspection wrapper](../../internal/framework/llm/promptkit_in Select application scope and observer/group enrollment for the agreed diagnostics. Implement the selected completion report and retire superseded manifest, receipt, and execution-ledger machinery. Coordinate command migration and debug capture -with the CommandKit notepad and master roadmap reconciliation. The core +with the incorporated design in the master roadmap. The core bookkeeping ownership change needs no new PromptKit capability; any remaining upstream request should identify a concrete unmet requirement. diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md index 9d2945fe..97d49c62 100644 --- a/docs/roadmap/promptkit.md +++ b/docs/roadmap/promptkit.md @@ -1,24 +1,27 @@ -# PromptKit-Native Architecture Migration +# Native PromptKit And CommandKit Migration ## Purpose And Status -Make Notarius fully PromptKit-native: use upstream configuration, execution, -continuation, admission, inspection, and accounting directly, and retain the -application work of producing, assessing, storing, and reusing typed artifacts. -Historical duplication of PromptKit behavior is not a requirement to preserve it. +Make Notarius fully native to PromptKit, ConfigKit, and CommandKit. Use upstream +configuration, execution, continuation, admission, inspection, commands, and +presentation directly. Retain the application work of producing, assessing, +publishing, and reusing typed artifacts. Historical duplication of library +behavior is not a requirement to preserve it. -This is the implementation roadmap for the agreed directions in items 1–6 of -[the architecture discussion record](promptkit-architecture-discussion.md). -That document retains the discussion and Audita evidence. This roadmap owns the -selected target, unresolved choices, implementation sequence, and acceptance -criteria. All implementation phases below are pending; rewriting the roadmap -has not changed application behavior. +This roadmap incorporates the [PromptKit architecture discussion](promptkit-architecture-discussion.md) +and all six items of the [CommandKit discussion](commandkit-migration-discussion.md), +including the subsequent accepted-artifact cache and artifact-first output +decisions. The notepads retain rationale and Audita evidence; this document owns +the selected target, unresolved choices, implementation sequence, removal +inventory, and acceptance criteria. All implementation phases are pending. +Recording these decisions has not changed application behavior. -The core migration is a hard cutover for application configuration and PromptKit -resource definitions. Supply migration guidance and maintained examples; support -only the new formats in the resulting application. CommandKit adoption remains a -subsequent delivery phase with its ownership accounted for throughout this plan. -Release preparation and publication are separate work. +Complete one coordinated cutover for configuration, PromptKit resources, and the +CLI. Adopt native public conventions fully; preserving old CLI behavior is a +non-goal. Supply migration guidance and maintained examples instead of aliases, +parallel parsers, or compatibility wrappers for legacy behavior. CommandKit is +part of the main migration, not a later follow-up. Release preparation and +publication remain separate work. ## Baseline And Dependency Target @@ -27,20 +30,34 @@ uses configuration version 5 and Go 1.27. Its dependencies include old-path PromptKit v0.12.0 and ConfigKit v0.5.0, new-path ConfigKit v1.2.0, go-yaml v4.0.0-rc.6, and two external PromptKit provider catalogs. -The initial dependency target remains `go.maximumdirect.net/promptkit@v0.23.2` -(tagged revision `382ccfb14b9630fd8f48c8364dbe2b6159637d71`), with shared -ConfigKit v1.2.1, stable go-yaml v4, and compatible validation dependencies. -The Go consumer minimum remains 1.27. The tagged [release notes][release], -[migration guide][migration], [format reference][formats], and -[Go consumer guide][consumer] supply the upstream baseline. +The selected reviewed baseline is: -Confirm the final compatible tagged dependency set before implementation. -A demonstrated unmet application need may justify an upstream request and a -later target; the agreed design does not currently require a new PromptKit -feature. In particular, neither a cross-backend global limit nor a comprehensive -execution fingerprint is a prerequisite. Remove obsolete imports and catalog -dependencies when unused; do not retain a compatibility fork or permanent -`replace` directive. Update attribution under the [OSS policy](../policy/oss.md). +| Module | Version | +| --- | --- | +| `go.maximumdirect.net/commandkit` | `v0.7.0` | +| `go.maximumdirect.net/ckconfig` | `v0.9.0` | +| `go.maximumdirect.net/ckprompt` | `v0.10.0` | +| `go.maximumdirect.net/configkit` | `v1.2.1` | +| `go.maximumdirect.net/promptkit` | `v0.23.3`, pending the message-content hash addition below | + +Keep Go's consumer minimum at 1.27, adopt stable go-yaml v4, and resolve compatible +validation dependencies. PromptKit v0.23.3 supersedes the initial v0.23.2 target +for its timeout/cancellation fixes. These are selected versions, not a claim +that they are the latest releases. The local tag review and integration guidance +are recorded in [CommandKit item 1](commandkit-migration-discussion.md#1-adoption-scope-and-dependency-baseline). +The tagged [release notes][release], [migration guide][migration], +[format reference][formats], and [Go consumer guide][consumer] supply the baseline. + +The cache requires the proposed native `MessageContentHash`. The +[upstream request](../../../promptkit/docs/roadmap/notarius-request.md) is pending; +v0.23.3's `RenderedPromptHash` is not a substitute. Confirm the supplying API and +tagged release, then verify the assembled dependency set. Independent composition +and pipeline work can proceed while that addition is pending; the completed +cache must use the upstream capability. Do not add a local hash-policy fork. +Neither a cross-backend global limit nor a comprehensive execution fingerprint +is required. Remove obsolete imports and catalog dependencies when unused; +avoid permanent `replace` directives and update [attribution](../oss/attribution.md) +under the [OSS policy](../policy/oss.md). Audita's reviewed v0.23.2 integration demonstrates native source assembly, continuation, observations, and CommandKit wiring. Adopt those mechanisms @@ -58,7 +75,7 @@ Notarius's artifact and recovery policies. | Artifact-family modules | Prepare domain inputs, select prompt IDs and response requirements, interpret responses, and apply deterministic domain rules. | | Pipeline execution | Connect generation to configured validation and terminal policy; manage ordered dependencies, typed handoffs, bounded workers, and stable result ordering. | | PromptKit | Prepare and execute requests; maintain captured exchanges and conversations; enforce native retry, repair, turn, and admission budgets; report execution facts. | -| Application state and records | Store artifacts, apply checkpoint reuse policy, preserve acceptance provenance, and attach pipeline context to execution facts. | +| Application state and records | Publish artifacts, cache final accepted artifacts, provide a small completion summary, and capture optional debug evidence with pipeline context. | | ConfigKit and CommandKit | ConfigKit owns configuration mechanics; CommandKit and ckconfig/ckprompt own standardized commands and presentation. Notarius supplies loaders, request builders, report content, and outcome mapping. | Use native PromptKit requests, results, exchanges, errors, and observers in @@ -81,6 +98,117 @@ and deterministic public ordering. Keep modules independent of physical output, cache, and debug roots. Native adoption does not turn the pipeline into a general workflow engine or redesign durable D&D artifacts. +### Command Surface And Native Inputs + +Install the application `pipeline` family alongside ckconfig and ckprompt: + +| Command | Responsibility | +| --- | --- | +| `pipeline list` | Discover configured pipelines. | +| `pipeline show ` | Report resolved steps, lanes, modules, validators, and reference relationships. | +| `pipeline validate ` | Check composition and known prompt/profile dependencies offline. | +| `pipeline run --input-file PATH` | Execute the pipeline and publish artifacts. | +| `run --input-file PATH` | Native alias for `pipeline run`, with the same handler and inputs. | + +Use `commandkit.Alias("run", "pipeline run")`, not a forwarding command. Use +`notarius run` in quick starts and document both routes. Install the full selected +standard suite: native help/version; Bash, Zsh, and Fish completion; configuration +scopes, validation, show, sources, explain, and diff; PromptKit resource listings +and inspection for prompts, profiles, backends, namespaces, and collections; +requirements discovery/validation and prepared-request preview; and explicit +reachability, authentication, text, structured-output, and aggregate smoke tests. +Include upstream convenience aliases and useful completion hints. + +Use native typed declarations and supplied-value semantics. Defaults apply to +omission, not explicit empty/false/zero values. Preserve native command-path, +operand, repeated-flag, and `--` parsing conventions. Check every occurrence of +a singleton flag and use the last successfully parsed value. + +| Concern | Selected input | +| --- | --- | +| Configuration | Native `--config`, `--overlay`, and supported application `--set POINTER=JSON`; scope named `app`. | +| Pipeline input | Required pipeline-ID operand and `--input-file PATH`. | +| Lanes | Repeatable `--lane ID`; omission selects the normal lane set. Commas are literal values, not separators. | +| Output | Application `--output-dir PATH`. | +| Chunk-plan cache | `--chunk-cache auto\|bypass\|refresh`. | +| Accepted-artifact cache | Reuse/bypass/refresh controls; spelling, scope, and defaults remain U8. | +| References | Repeatable `--reference SELECTOR=PATH` and `--without-reference SELECTOR`. | +| Presentation | Native `--format`, `--quiet`, `--verbose`, `--debug`, and `--progress`. | +| Capture destination | Application `--debug-dir PATH`, with the semantics below. | + +Keep worker counts and semantic budgets in configuration, adjustable through +application `--set`; their fields/defaults remain open. Use ckprompt's reusable +profile, session, and execution flags, including model, temperature, timeout, +reasoning effort, and transient retries, for run-wide overrides across producers, +validators, and continuations. Omission preserves normal selection; explicitly +empty reasoning effort clears inheritance. Use native `--llm-profile` and +`--llm-session-id`, retiring the separate reasoning-clearing control. Native +transient retries remain distinct from semantic additional-turn budgets. +Individual prompt selection and named prompt inputs belong on standard PromptKit +commands; pipeline modules build their own requests. + +Notarius retains reference-selector expansion, specificity, required slots, and +external/generated-reference conflict checks. Pipeline reference selectors are +not individual-request `--llm-input-file` bindings. Remove custom dispatch, +assembled help, standard flag parsing, comma-separated `--only`, and bespoke +`--json` switches. Replace `config effective` with `config show` and `config +profile` with `promptkit show profile`. Old flags are migration evidence only. + +### Application Composition, Loaders, And Preflight + +One constructor registers application commands, the native alias, ckconfig's +`app` and `promptkit` scopes, ckprompt, and native help/version/completion/reporting. +It does not load configuration, build an engine, or initialize run storage. +Help, version, and completion work without application configuration. + +Share two loading responsibilities across application and standard commands: + +1. Select application configuration through explicit `--config`, then existing + environment/discovery policy. Let ConfigKit apply overlays, imports, + inheritance, overrides, defaults, normalization, and structural validation. + Retain its native result and selected main-source context. Validate an + explicitly empty configuration path rather than falling through to discovery. +2. Build the native engine from that application's source context using the source + assembly below. Across commands, `--config` selects the application document; + the PromptKit scope inspects the engine assembled for it. Request overrides + do not mutate captured engine configuration. Do not emulate unsupported + arbitrary `--set` overrides for the PromptKit scope. + +Use small invocation-owned state through CommandKit's facilities to reuse loaded +values. A pipeline shares one engine across all roles. `config diff` may load two +distinct configurations within one invocation: keep their selections separate, +including overlays/overrides. No persistent loader cache or configuration hash +framework is needed. + +Reuse the application resolver for module/options checks, typed compatibility, +ordered dependencies, validator chains, and reference bindings. `pipeline list` +only enumerates configuration; `show` renders resolved composition rather than +building an engine to expand every profile. ConfigKit supplies loaded values and +native provenance/secret-aware inspection, not domain pipeline semantics. + +Centralize known prompt/profile dependency checks in `internal/preflight`. It +accepts the resolved pipeline, module declarations, and native engine. Check +every statically known dependency, including LLM validators and correction +prompts, plus applicable/default profiles. Partial profiles alone are not errors. +Share identifiers and selection logic with execution; no independent inventory, +asset registry, or synthetic request execution is needed. Dynamic selections +receive their final checks at runtime. Findings identify pipeline, step/lane, +stage/validator, and resource where applicable. + +`pipeline validate` and `run` call the same resolution/preflight functions; +handlers do not invoke other commands or parse their reports. Keep `config +validate` focused on configuration and remove its pipeline-specific mode. +Offline preflight reads configuration and prompt resources but needs no transcript, +reference contents, credential values, or provider calls. Concrete PromptKit +preparation/validation owns completed-request checks, including schemas and +credentials; provider smoke tests require explicit invocation. + +Preflight does not discover configuration, register modules, build engines, +initialize storage, or render CLI reports. Modules do not import it. Use native +request builders for standard commands and add application callbacks only where +needed, preserving supplied operator values. Output/cache/debug allocation +belongs to the run path, with debug timing selected below. + ### Configuration, Sources, And Prompt Assets Introduce application configuration version 6 as the only supported version. @@ -142,7 +270,8 @@ contexts and imports rather than reconstructed virtual trees. PromptKit owns private model-response validation and structural repair. Native schemas resolve against the configured schema root, separately from message-file -contexts, and v0.23.2 requires self-contained schemas loaded during preparation. +contexts. The reviewed baseline requires self-contained schemas loaded during +preparation. A request override replaces the complete output contract; it must retain the intended schema, validation mode, and repair policy. A prompt hash alone does not establish schema equality. @@ -164,11 +293,14 @@ Per-entity branching is not part of this migration. The application flow is: 1. Prepare source context, references, and candidate-handle mappings once. Build - the native initial request and call `Engine.Run` with exchange capture when - continuation is enabled. Capture is independent of detailed debug recording. -2. Check native structural validation, decode, and apply module interpretation - and safety checks. A module can supply actionable findings before it has a - materialized candidate. Run configured artifact validation on each candidate. + the native initial request. For cacheable work, prepare and check the cache + before execution as described below; execute the retained request on a miss. + Otherwise use ordinary `Engine.Run`. Capture an exchange when continuation + or debug inspection needs one. +2. Consume the native usable response or terminal failure, decode, and apply + module interpretation and safety checks. A module can supply actionable + findings before it has a materialized candidate. Run configured artifact + validation on each candidate. 3. For actionable correction, call `Engine.Coordinate` with the captured exchange and `AdditionalTurns`. Its callback selects a repair prompt and supplies findings; PromptKit retains the initial exchange and subsequent turns. @@ -217,11 +349,11 @@ acceptance. Preserve rejection versus unavailable/incomplete validation. A structurally valid candidate may advance under the existing `warn_continue` policy with -explicit incomplete-validation provenance, but it and its affected derivatives -cannot be loaded from or published to reusable checkpoint/cache state. A +explicit incomplete-validation outcome information, but it and its affected +derivatives are ineligible for accepted-artifact cache reuse or publication. A completed rejection never advances. Cancellation cannot make an undelivered response accepted. Keep conversation state in process, outside ordinary -manifests and checkpoints; explicitly requested detailed debug is separate. +artifact/cache payloads; explicitly requested detailed debug is separate. ### Admission And Pipeline Workers @@ -236,9 +368,11 @@ backend IDs or separate engines do not automatically share limits, even for the same endpoint. Endpoint-only profiles and backends without a positive limit remain unrestricted by native backend admission. -For limited backends, v0.23.2 bounds active model attempts by `concurrency_limit` -and admitted operations by that limit plus `queue_capacity`. Admission spans -preparation, retries, and repairs; active permits are released during retry waits. +For limited backends, the reviewed baseline bounds active model attempts by +`concurrency_limit` and admitted operations by that limit plus `queue_capacity`. +Ordinary execution admission spans preparation, retries, and repairs; split +`PrepareExecution` itself reserves no capacity, with admission occurring during +`RunPrepared`. Active permits are released during retry waits. A completed continuation turn releases admission before assessment, allowing a nested validator to use the same backend. Configure native limits at the intended capacity boundary and handle `ErrCapacityExceeded` through application policy. @@ -248,272 +382,445 @@ ceiling. That change is intentional. Bounded pipeline workers are application work controls, not a substitute cross-backend LLM ceiling. Defaults, retired-field migration, and role-specific admission-failure dispositions remain open. -### Checkpoint Reuse For Successful Work +### Accepted-Artifact Cache -Checkpoints support recovery after a downstream failure: fixing a later stage -should not require rerunning earlier successful work. Use this conceptual key: +Replace the checkpoint subsystem with a cache around the complete Notarius +producer operation. Its value is an accepted answer to the original task. This +avoids repeating expensive model work after a downstream failure without caching +every cheap deterministic pipeline step. ```text -logical stage identity + input-data identity + prompt ID, where applicable +Prepare initial request -> obtain MessageContentHash -> look up cache/.json + Hit: decode the accepted artifact and continue the pipeline + Miss: execute the retained request and complete the Notarius operation + -> interpret, validate, and perform application-directed corrections + -> on final acceptance, store the artifact under the INITIAL hash ``` -Scope logical identity to the relevant step/lane/stage and artifact kind, without -hashing complete configuration or implementations. Inputs include actual source -or chunk data, reference material, and consumed upstream artifact content. -Deterministic stages need no synthetic prompt ID. Content digests can represent -inputs and verify payload integrity without fingerprinting the execution setup. +Use the proposed upstream hash of ordered message roles and exact text. Include +message boundaries and order, excluding model/settings, session/execution IDs, +timing, provider cache hints, and other non-content metadata. Add no stage, +prompt-ID, library-version, whole-configuration, schema-policy, or implementation +fingerprint. Actual input or schema text rendered into messages participates as +message content; metadata outside those messages does not. | Change | Intended reuse behavior | | --- | --- | -| Fix a later failed stage | Reuse successful predecessors with matching logical work and inputs. | -| Edit prompt content while keeping its ID | Reuse; explicit recomputation applies the edit. | -| Change model, generation settings, implementation, or validation policy | Reuse otherwise usable completed work; explicit recomputation applies improvements. | -| Change the prompt ID or consumed source/reference/upstream data | No matching checkpoint. | -| Request explicit recomputation | Recompute the selected work and its dependents. | +| Fix a downstream stage | Earlier artifacts remain reusable when their initial messages match. | +| Change initial message text, roles, order, or boundaries | Cache miss. | +| Change a prompt ID, model, or settings without changing messages | Cache hit remains possible. | +| Change deterministic interpretation or validation | Existing accepted artifacts remain reusable; explicit bypass/refresh applies the new policy. | -Keep recording separate from reuse. The existing controls are -[`--resume` and `--recompute-step`](../cli.md#run); migrate their compatibility -behavior to this policy. A matching key does not make an unreadable, corrupted, -or incompatible artifact usable. Retain acceptance/completion status, integrity, -and decode/consumer compatibility checks. Exact schema hash equality is not -required for a compatible artifact. +Obtain the key before model execution through native preparation. Preserve the +prepared snapshot for execution on a miss using `PrepareExecution`/`RunPrepared` +where supported, and discard the handle on a hit. `OnPrepared` execution hooks +alone cannot short-circuit execution. v0.23.3's `RenderedPromptHash` includes +session identity and cache hints; it is not the requested hash. The upstream +request in U1 must land before completing this cache integration. -Only accepted, completely validated work is reusable. Preserve original -execution and acceptance provenance; do not rerun semantic validators solely -because their configuration changed or claim the old artifact passed a new -policy. Retain the exclusion of rejected, structurally invalid, and -validation-incomplete work and its ineligible derivatives. The accepted tradeoff -is reuse of results produced by prompts, settings, or code that have improved. +Keep the initial key throughout corrections. Cache the final Notarius artifact +through its existing codec, not an intermediate response, `RunResult`, exchange, +or prepared handle. For normalization, save the accepted normalized artifact +after applying the reconciliation plan, not the proposed plan itself. Save only +after the entire Notarius operation succeeds, including domain validation and +any application-directed corrections. Failed, rejected, and validation-incomplete +work and ineligible derivatives are not cacheable. -Remove whole PromptKit configuration, catalog/library versions, model settings, -prompt-content hashes, and component-policy fingerprints as matching criteria. -Native hashes may remain diagnostic metadata. Revise storage/lookup scoping so -an invocation-wide pipeline/configuration digest cannot still block recovery. -There is no need for an upstream semantic-equality feature, persisted conversation, -native prepared-execution handle, or temporary conservative fingerprint. +A hit loads the accepted artifact directly, with ordinary decoding/usability +checks; absent or unusable entries are misses. It makes no model calls, rebuilds +no result/exchange, replays no corrections, and performs no new semantic +validation merely because the artifact was cached. It makes no claim of acceptance +under changed validation policy and contributes no historical token usage to +current execution totals. -Keep the separate source-addressed canonical chunk-plan cache policy, including -current validation of materialized chunks. Concrete checkpoint identifiers, -input representation, old-record transition, and incompatible-payload reporting -remain open. +PromptKit owns everything inside each native request, including structural +validation, transport retries, and repairs. Notarius consumes its public response +or terminal failure and owns domain acceptance. Internal PromptKit attempts do +not determine cache eligibility. Native diagnostic evidence does not transfer +that ownership. No cached-response injection, replay API, exchange restoration, +or PromptKit-owned write-through cache is requested. -### Inspection, Bookkeeping, And Presentation +Use a small filesystem lookup/write facility and ordinary temporary-file/rename +publication. `cache/.json` contains the artifact, with no required manifest, +acceptance ledger, historical provenance, or versioned checkpoint envelope. +Lookup does not require original output or debug directories. Remove checkpoint +identities, dependency fingerprints, invocation-wide barriers, and recovery +bookkeeping. Preserve the separate canonical chunk-plan cache and its materialized +chunk validation. Cache directory configuration, reuse/bypass/refresh controls, +and handling of old checkpoint files remain U8; old `--resume`/`--recompute-step` +conventions are not compatibility requirements. -Use native configuration/resource inspection rather than effective-YAML parsing, -a profile-inspector wrapper, or copied effective-model-parameter types. A profile -can be partial; its inspection is not the completed execution target. Use actual -prepared/result data for execution provenance, including request overrides, and -record the profiles/targets used rather than the available catalog. +### Inspection And Execution Bookkeeping -Keep application pipeline preflight for modules, typed artifact compatibility, -reference bindings, and known prompt/profile selections. `config validate` checks -resolved application configuration; with a pipeline selection, load the same -native definitions used by execution, including a known prompt's default profile -when effective. Do not simulate stages to discover dynamic selections. Preflight -needs no transcript, credential values, or provider call. Use native requirement -inspection for explanation and concrete `Prepare`/`ValidateRequest` for completed -target, input, schema, and credential checks when requested. Partial profiles -alone are not preflight failures. +Delegate configuration/resource inspection, requirements, concrete preview and +validation, and explicit smoke diagnostics to ckconfig/ckprompt through the shared +loaders. Remove effective-YAML parsing, the profile-inspector wrapper, and copied +effective-parameter types. A configured profile may be partial; use native +prepared/result details for the actual execution target, including overrides. +Standard commands retain their native reports, support/applicability distinctions, +and failure behavior. Smoke status zero alone does not prove a check passed. -Use ordinary `Run` with `OnPrepared` for needed actual request details and optional -debug capture. Remove forced `PrepareExecution`/`RunPrepared` solely for recording. -`OnPrepared` runs after preparation/admission and before generation; it is absent -on preparation/admission failure and cannot be a terminal record. Native -observations supply terminal facts even when a failed call returns no `RunResult`. -Keep callbacks lightweight and synchronize shared observation state as required. +Use ordinary `Run` with `OnPrepared` when actual request details are needed for +diagnostics; split preparation has a separate purpose for cache lookup. Native +observations provide terminal facts even without a returned `RunResult`. +`OnPrepared` is absent on preparation/admission failures and is not a completion +record. Keep synchronous callbacks lightweight, compose capture/accounting +observers, and synchronize shared state where operations overlap. -Use native `RunID`/`ParentRunID` plus application step/lane/chunk/validator scope. -Remove duplicate `LLMExecutionSummary`, usage types, enum conversions, cloning, -independent accumulators, debug completion wrappers, and redundant synthetic -call IDs. Replace adapter profile-recording/forwarding with only the projection -needed at application boundaries. Preserve native failure distinctions while -Notarius chooses domain outcomes and exit-status mapping. +Use native `RunID`/`ParentRunID` with application step/lane/chunk/validator scope. +Remove `LLMExecutionSummary`, duplicate usage types, conversions, cloning, +independent accumulators, debug completion wrappers, synthetic call IDs, and +adapter profile-recording/forwarding. Native snapshots serve actual-target +inspection; do not reconstruct a durable profile inventory. -Use `ExecutionGroup` for totals over selected executions. Enroll the initial run, -continuation runs, and nested validator executions explicitly as applicable. -Preserve terminal coverage and usage completeness: unknown usage is not zero. -Avoid counting both attempt and terminal aggregates or adding overlapping groups. -Provider execution success remains separate from domain acceptance. +Use `ExecutionGroup` for selected diagnostic totals, explicitly enrolling initial, +continuation, and nested validator executions without overlapping double counts. +Preserve terminal coverage and unknown-versus-zero usage. Reuse adds no historical +usage to current totals. These facts support diagnostics and capture, not a +mandatory consumer execution ledger. Notarius's acceptance, fallback, rejection, +incomplete-validation, publication, and reuse facts feed the completion summary +and debug overview without independently maintained reporting state. -Retain application records of acceptance, rejection, validation completeness, -fallback, generation versus reuse, and pipeline outcome. Reused artifacts retain -original provenance; the current invocation records reuse without counting old -token usage as current work. Keep small deliberate projections for the -[published manifest](../integrations/json-output.md) and -[run-result receipt](../integrations/run-result.md), with explicit compatibility -decisions. Do not serialize complete upstream runtime types as durable contracts. +### Artifact Delivery And Completion Output -Notarius retains debug placement, opt-in capture, retention, and disclosure -handling, including credential redaction. Native callbacks provide the data; -ordinary provenance retains only needed fields, and sensitive response/history -content stays out of ordinary records. Debug is not checkpoint input. +Artifacts are the primary deliverable: publish accepted domain artifacts as files +in the output directory. Preserve intrinsic domain content and artifact schemas. +CLI `--format` controls the completion report, not payload encoding. Consumers +need no run manifest, metadata bundle, persisted receipt, or execution history to +use the artifacts. Retire reporting-only metadata and mandatory manifests instead +of rebuilding them with native values. -CommandKit with ckconfig/ckprompt is the selected owner of standardized -configuration/resource commands, requirements, validation, preview, opt-in smoke -diagnostics, formatting, visibility, and progress presentation. Notarius supplies -loaders, request builders, report content, pipeline meaning, and outcome mapping. -Keep machine-output receipts deliberate and presentation delivery failures -distinguishable from operation outcomes. Until that follow-up lands, make only -the changes needed to keep existing inspection commands usable through native -APIs; do not build temporary custom commands or a new reporting framework. +Submit one small structured value through `Reporter.Report`: + +| Field | Meaning | +| --- | --- | +| `pipeline` | Selected pipeline identifier. | +| `artifact_count` | Deliverable artifacts, including reused artifacts; excludes intermediates, cache entries, and debug files. | +| `output_directory` | Absolute published artifact directory. | +| `debug_directory` | Optional absolute completed run-specific capture directory; omitted when capture is disabled. | + +Supply a native text template for the ordinary successful case: + +```text +Success: dnd-session produced 6 artifacts in /work/results/run-123 +``` + +When capture is available, append `Debug capture: `. Provide the +path rather than mirroring the bundle. JSON/YAML render the same structured +value through native serializers. A plain string would render natively as text +but lose named fields in machine output; the template gives both presentations +without parallel encoders. No report-version, run-ID, token, profile, warning-count, +or validation-history collection is required. + +When a completed run includes rejected work or permitted incomplete validation, +qualify the human summary and structured value with the rejection count and/or +incomplete-validation fact. Keep these facts visible without verbose/debug mode; +small outcome qualifications do not require per-producer histories. Exact names +of those conditional fields are implementation details. + +Wire results to stdout and diagnostics to stderr: + +| Mode | Stdout | Stderr | +| --- | --- | --- | +| Ordinary | Brief completion report. | Failure explanation when needed. | +| `--verbose` | Same completion report. | Native information, warnings, and failures. | +| `--quiet` | Nothing. | Failure explanation when needed. | +| `--debug` | Completion report with capture path when enabled. | Native diagnostics and default progress. | + +Use native mode ordering (last enabled mode wins), explicit progress selection, +and quiet suppression. Quiet still permits failure explanations and does not +prevent rendering errors from failing the invocation. `--format json --verbose` +keeps stdout valid report JSON. Standard configuration/PromptKit commands retain +their own native values, with no universal Notarius envelope. Artifact-quality +advisories retain their domain classification. + +Optional saved reports use shell redirection, without a report-file flag or +automatic duplicate persistence: + +```sh +notarius run dnd-session --input-file transcript.json --format json > run-report.json +``` + +Publish artifacts and finish requested capture before submitting a successful +completion report. Use native outcomes: status 0 for command completion, 1 for +operational/cancellation/publication/presentation failure, 2 for invalid invocation +or identifiable invalid configuration, and 3 for native `config diff --check` +differences. Preserve ckconfig's structured classification and underlying causes; +not every preflight failure is invalid input. Command completion is distinct from +domain acceptance: permitted rejections/incomplete validation qualify the report, +while terminal pipeline failure fails the command. + +On failure, supply a useful native explanation and nonzero status, without a new +structured error-envelope protocol. `--format` does not serialize diagnostics. +Retain CommandKit's separation of operation causes from output/diagnostic delivery +failures. If publication succeeded before capture/report delivery failed, identify +the published path and available debug location. Published artifacts remain valid; +do not rerun model work or rewrite execution history. Subprocess callers check +status before decoding a successful report; failed writes may leave partial stdout. + +### Debug Capture And Optional Diagnostics + +Capture the **most convenient** debug representation, rather than optimizing +for conciseness, exhaustive completeness, or strict deduplication. Native snapshots +and readable views may repeat evidence. Reuse application decisions and native +execution facts instead of maintaining a second ledger or transcript model. +Debug formats are diagnostic data, not stable consumer contracts. + +#### Controls And Location + +Bind an application boolean to native `--debug`. Capture requires that boolean +and a nonempty effective directory; a directory alone does not enable capture. +Select `--debug-dir PATH` over `debug.directory` over `/tmp/notarius-debug`. +Resolve nonempty configuration-relative paths against their source and CLI-relative +paths against the invocation directory. Recognize explicit empty values first: +`--debug-dir ""` or `debug.directory: ""` disables capture without fallback. +A nonempty CLI override can re-enable capture over an empty configured root. +An unusable nonempty destination fails requested capture rather than selecting +another directory. Remove the configuration-relative `./notarius-debug` default. + +Capture selection is independent of the final reporting mode. `--debug --quiet` +captures while suppressing stdout; `--quiet --debug` selects debug verbosity and +capture. `--debug=false` disables capture through native binding semantics. +Empty-directory debug retains native verbosity. No separate capture flag or +capture-depth switch is needed. + +#### Lifecycle And Failure Handling + +Allocate the run bundle after application configuration and run identity are +available, before engine construction and pipeline preflight. Argument/config-load +failures may have no bundle. Keep allocation out of shared loaders. + +Create `//` and update `/latest` to a relative +symlink to that run at session start. It points to the newly started session even +if that session fails. Do not retarget at completion; concurrent starts use the +last successful link update. Runs without capture leave it untouched. + +One application recorder accepts initial context, native evidence, and application +decisions, then finalizes once with pipeline/publication/capture outcomes. Persist +as operations advance, without holding the whole pipeline's content in memory. +Keep debug separate from output/cache and do not automatically delete bundles. + +Requested capture is required work: allocation/link failures stop before model +work; recording failures surface at the next normal application boundary; +finalization failure fails the command. Observer callbacks retain errors for +boundary checks because they cannot return errors. An existing pipeline failure +remains primary, with capture failures reported additionally and causes retained. +Already-written data and published artifacts remain available. Capture failures +never cause model retries. Finalize before submitting the success report. + +#### Inventory And Depth + +Replace separate summary/trace categories with a compact run overview, +configuration/composition snapshots, parsed source, and per-operation records. +Use native execution IDs with application scope for navigation. `latest` is the +selected link name; other filenames and serialized application fields remain +implementation choices. + +| Capture | Selected contents and depth | +| --- | --- | +| Run overview | Application version, run/pipeline identity, timing, outcome, publication location, effective invocation selections/overrides, and navigation. Terminal facts come from the same application outcome used by the CLI. | +| Configuration and composition | Native application and PromptKit effective snapshots, normally once each, plus resolved steps, lanes, modules, validators, and references. | +| Parsed source | Generic input document with unit identities and content, independent of the original input file. If parsing fails, retain the input location and available diagnostics. | +| Operation inputs | Actual source/chunk and reference content, incoming artifacts, prompt bindings/variables, and fixed original normalization candidates/handle mappings. Include directly even when duplicated elsewhere. | +| Prepared requests | Native `PreparedRun`, including settings, messages, and exposed output-contract/schema details when available. | +| Execution events | Native per-execution events in occurrence order, including attempts/retries/repairs, timing, usage availability, and terminal metadata. | +| Results and responses | Native `RunResult` plus exact `RawOutput` in a separate editor-readable text file. | +| Conversations | Full `Exchange.Details()` for every application-visible turn, including rejected turns, plus simple readable role-labeled messages. Repeated prefixes are acceptable. Use prepared messages when no completed exchange exists and label the representation. | +| Interpretation and assessment | Candidate via its codec before acceptance; decode/safety failures; each validator's findings and correction guidance; application disposition and links to LLM validator executions. | +| Normalization and corrections | Proposed reconciliation plan and applied candidate; constructed correction inputs even if the next preparation fails. | +| Deterministic stages and reuse | Chunk plans/materialized chunks, merged/normalized artifacts, and the loaded cached artifact with the current hit decision. No reconstructed history or fabricated execution on reuse. | + +Use indented JSON for native structured snapshots and existing domain codecs. +Retain selected content in full, with no arbitrary truncation. Enable exchange +capture where debug inspection requires it, including single-turn calls; +continuation's in-process exchange needs remain independent of durable capture. +Keep operation inputs self-contained enough for direct investigation without +requiring original inputs, a cache entry, or reconstruction of deltas. Do not +archive every original file or serialize the pipeline's entire internal state. + +On failure, retain available evidence, where execution stopped, errors, and +application disposition. Preparation/admission failure may have no `OnPrepared`; +operational failure may have no `RunResult`. Capture a coordination `Undelivered` +response as unassessed. Native internal-attempt metadata is useful but intermediate +provider response bodies are not required. No provider wrapper or complete +provider-transcript guarantee is part of this design. + +#### Data Handling And Diagnostic Commands + +Operators secure debug data as they secure ordinary application inputs and +outputs, for example with filesystem permissions. Debug contains internal data; +no separate security/retention model or sanitized-bundle promise is required. +Do not directly print/serialize ConfigKit-marked secrets, and preserve native +credential omissions through secret-aware inspection. Do not heuristically scan, +scrub, or rewrite prompts, source material, model output, or arbitrary strings. + +Inspection/diagnostic commands use native reports and do not automatically create +pipeline debug bundles. Operators may redirect those reports. Neither debug mode +nor capture initiates provider probes. Explicit smoke checks retain native +support, applicability, and outcome distinctions. ## Unresolved Choices -The directions above are selected. The following details are not. Resolve and -record each choice before implementing the work that depends on it; independent -work need not wait for every choice. Candidates here are not implicit defaults. +The architecture and public direction above are selected. Resolve each remaining +choice before its dependent work; independent work need not wait. Routine API +placement and serialization choices are implementation details, not reasons to +reopen the architecture. IDs retain continuity with the earlier roadmap. -| ID | Choice still needed | Resolve for | +| ID | Remaining choice or dependency | Resolve for | | --- | --- | --- | -| U1 | Final compatible tagged PromptKit/ConfigKit/dependency set; any specific unmet need requiring an upstream request. v0.23.2 is the initial target, not a restriction on useful upstream work. | Phase 1; revisit if the target or upstream needs change. | -| U2 | Remaining custom read-only filesystem responsibilities; schema root/path and assembly, prompt-declared versus per-request contracts, removable wrappers, and metadata useful for manifests/artifact compatibility. | Phase 2 source and schema assembly. | -| U3 | Concrete module/pipeline signatures and placement of engine assembly, request construction, interpretation, assessment, and focused helpers. | Phase 3 representative workflow, refined during Phase 4. | -| U4 | Initial and repair prompt definitions, response contracts, and profile selection within complete replacement and fixed operation inputs. | Phases 3–4 for each producer role. | -| U5 | Mapping producer/validator retry settings to native controls; names, defaults, compatibility, non-LLM failure handling, and any explicitly justified recovery beyond native exhaustion. | Phases 3–4 and configuration migration. | -| U6 | Detailed terminal/fallback dispositions, especially whether any earlier safe candidate survives a later failed turn. | Phases 3–4; no implicit best-so-far acceptance. | -| U7 | Independent worker defaults, native backend/queue defaults where supplied, retired `total_llm` migration, and admission-failure handling by role. | Phase 4 shared-engine cutover. | -| U8 | Logical checkpoint/prompt identifiers, consumed-input representation, storage scoping, old-record transition, and load-compatibility reporting. | Phase 5 recovery migration. | -| U9 | Minimal durable fields and their compatibility treatment; observer/group enrollment, application scope, and debug write/disclosure handling. | Design with Phase 3, complete in Phase 5. | -| U10 | CommandKit/ckconfig/ckprompt versions, command exposure and compatibility, and application wiring for the follow-up. | Phase 7; do not recreate its machinery earlier. | +| U1 | Supplying PromptKit API/release for the requested message-content hash; verify the final compatible dependency set against the selected baseline. The upstream request is pending. | Track in Phase 1; required to finish cache integration in Phase 5. | +| U2 | Custom read-only filesystem responsibilities; schema root/path and assembly; prompt-declared versus per-request contracts; removable wrappers and useful artifact-compatibility/inspection metadata. Mandatory manifest metadata is retired. | Phase 2. | +| U3 | Concrete module/pipeline signatures and helper placement for request construction, interpretation, assessment, and native engine assembly. | Implementation detail in Phase 3, refined in Phase 4. | +| U4 | Role-specific initial/repair definitions, response contracts, and profile selection within complete replacement and fixed operation inputs. | Phases 3–4. | +| U5 | Producer/validator retry-setting migration to native controls and semantic budgets: field names/defaults, non-LLM failure handling, and any justified recovery beyond native exhaustion. | Phases 3–4 and configuration migration. | +| U6 | Detailed terminal/fallback policy, especially whether an earlier safe candidate survives a later failed turn. No implicit best-so-far acceptance. | Phases 3–4. | +| U7 | Independent worker defaults; application-supplied native backend/queue limits, if any; retired `total_llm` migration and admission-failure handling by role. | Phase 4. | +| U8 | Cache directory configuration and reuse/bypass/refresh controls (names, defaults, scope); old-checkpoint treatment and unusable-entry diagnostics. Hash inputs, lookup timing, accepted value, and ownership are settled. | Design with Phase 3; finish in Phase 5. | +| U9 | Observer/group enrollment and application scope; concrete conditional report fields and debug filenames/serialization within the agreed contracts; publication-layout/consumer migration details preserving intrinsic artifact schemas. | Implementation details in Phases 3–5; no new receipt/manifest inventory or capture-policy decision required. | + +**U10 resolved:** CommandKit versions, capabilities, commands, loaders/preflight, +output, debug policy, and coordinated cutover sequencing are selected above. +The former later CommandKit phase is retired. CLI compatibility is a non-goal; +existing artifact schemas remain domain contracts. Any actual artifact-format +change discovered during implementation needs an explicit compatibility decision, +not an assumption that native CLI adoption authorizes it. ## Implementation Sequence -Each phase is pending. Phases describe reviewable outcomes and dependencies, -not separate releases. The supported core result is the hard cutover; any -intermediate migration scaffolding must retire before that result is complete. -Update affected canonical documentation as behavior lands. Record significant -boundary decisions in successor ADRs without rewriting accepted decision text. +All six phases are pending. Each delivers a reviewable outcome, not a separate +release or compatibility layer. Tests and canonical documentation accompany +behavior changes; the last phase verifies integration and completeness. Record +major boundary changes in successor ADRs without rewriting accepted decisions. ### Phase 1: Establish The Migration Baseline -- Confirm U1 against the tagged APIs and dependency graph. Carry forward the - Audita evidence without treating its wrappers as requirements. -- Map the changed architecture and ADRs, and identify concrete decisions needed - for the next phase. Keep unresolved entries visible until actually settled. -- Identify the production callers and old contracts covered by the removal - inventory below; use that inventory to track complete cutover coverage. +- Record the selected dependency set and track U1 against the upstream request. + Keep the cache dependency explicit without blocking independent work. +- Map affected ADRs, current callers, contracts, and removal inventory. Carry + forward Audita evidence without adopting its application wrappers. +- Preserve U2–U9 with their dependent phases; do not treat resolved CommandKit, + debug, cache, or output choices as requirements to redesign. -**Completion evidence:** selected dependency baseline and decision/implementation -scope are recorded; unresolved choices have a clear dependent phase. No new -upstream feature is assumed necessary without an identified requirement. +**Completion evidence:** reviewed dependency baseline, upstream dependency, scope, +and outstanding choices are explicit. This phase does not claim that the hash +already exists or that the migration is implemented. -### Phase 2: Assemble Native Sources And A Shared Engine +### Phase 2: Build Native Composition, Sources, And Preflight -- Resolve U2, update dependencies, and implement version 6 and companion-source - composition. Convert embedded resources and establish the schema loading path. -- Construct the shared native engine and use the same assembly for execution, - preflight, and inspection. Remove duplicate prompt assembly as callers migrate. -- Add maintained embedded-only and operator-override examples with the new format. +- Resolve U2, update available dependencies, introduce configuration version 6, + convert native embedded/companion resources, and establish schema loading. +- Build the small CommandKit application, shared ConfigKit/engine loaders, + standard suites, pipeline declarations/native alias, and `internal/preflight`. +- Add maintained embedded-only and operator-override examples. Remove duplicated + loading and asset assembly as callers migrate. -**Completion evidence:** offline preparation proves resource selection, shared -content/schema resolution, source precedence, and operator replacement. Invalid -sources fail rather than silently selecting defaults. Preflight needs no provider -credentials or synthetic stage execution. +**Completion evidence:** runtime/inspection/preflight share intended definitions; +source contexts, strict peer conflicts, and replacement work offline. Help, +version, and completion need no configuration. Preflight checks known dependencies +without credentials or synthetic requests. `config diff` handles two selections. -### Phase 3: Prove Native Production And Assessment +### Phase 3: Prove A Representative Native Pipeline -- Resolve U3 and the relevant U4–U6/U9 choices for a representative extraction - workflow. Connect native generation, domain interpretation, configured - validation, and continuation through the small application function. -- Exercise a configured LLM validator on the same engine. Attach native observers, - application scope, and selected execution-group membership from the start. -- Exercise normalization's fixed candidate handles and fresh plan application, - including the selected terminal/fallback policy. +- Resolve U3 and relevant U4–U6 details. Connect native generation, interpretation, + configured validation, and continuation through the application function. +- Exercise an LLM validator on the same engine and normalization with fixed + handles and fresh plan application. Select actual observer/group enrollment. +- Run through the new command surface and alias, using the small completion + report, native outcomes/streams, and useful debug capture from the outset. + Begin U8/U9 integration without a provisional local message hash. -**Completion evidence:** fake-provider workflows demonstrate accumulated history, -full revalidation, final-turn acceptance, correct exhaustion/failure handling, -and typed application outcomes without the private completion/correction API. +**Completion evidence:** fake-provider workflows exercise accumulated history, +full candidate revalidation, final-turn acceptance, selected exhaustion/fallback, +and useful failures. The executable publishes artifacts and reports them through +native presentation without the private completion/correction API. -### Phase 4: Migrate All Roles And Retire Runtime Machinery +### Phase 4: Migrate All Roles And Remove Superseded Machinery -- Apply the established flow to every LLM-backed chunker, extractor, normalizer, - and validator. Preserve deterministic stage paths and ordered validation. -- Complete U4–U7 across roles. Migrate retry controls, remove the global scheduler, - and give bounded pipeline workers independent configuration. -- Remove the adapter, copied completion contracts, correction-protocol checks, - outer LLM retry loops, and redundant asset registration once unused. +- Migrate every LLM-backed chunker, extractor, normalizer, and validator; preserve + deterministic paths and ordered validation. Complete U4–U7 across roles. +- Remove the adapter, copied completion contracts, manual replay/capability checks, + outer LLM retries, global scheduler/ceiling, and coupled worker settings. +- Finish native command/inspection migration and remove custom dispatch, flags, + encoders, verbosity handling, and obsolete asset registration. -**Completion evidence:** all production roles share native execution and admission; -no application path still depends on the retired completion API, global ceiling, -or latest-response-only correction. Native failures and cancellation settle -through the selected role policy. Tests for obsolete machinery retire with it. +**Completion evidence:** every role uses the shared native engine and selected +admission policy. No production path depends on the private completion API, +latest-response-only correction, global ceiling, or legacy CLI infrastructure. +Obsolete tests retire with the machinery; surviving domain requirements remain. -### Phase 5: Simplify Recovery And Execution Records +### Phase 5: Complete Cache, Output, And Capture Integration -- Resolve U8–U9. Implement logical-work/input/prompt checkpoint matching and revise - storage scoping so unrelated configuration changes cannot defeat recovery. -- Implement and document old-checkpoint handling, artifact usability checks, - original acceptance provenance, and explicit recomputation behavior. -- Complete native inspection, observation/group accounting, minimal durable - projections, and optional debug capture; remove the duplicate bookkeeping. +- Resolve U1's supplying release and complete U8. Implement lookup at initial + preparation, accepted-artifact storage under that hash, explicit cache controls, + and deliberate old-checkpoint handling. Keep canonical chunk caching separate. +- Complete the artifact-first publication/report contract and U9 details. Remove + checkpoint fingerprint graphs, mandatory manifests/receipts, durable execution + ledgers, and duplicate accounting; do not retain them to populate summaries. +- Complete capture inventory, per-operation evidence, directory/empty-value + behavior, `latest`, and recording/finalization failure handling. -**Completion evidence:** a downstream-failure/fix/resume scenario reuses successful -predecessors; settings changes do not spuriously invalidate them, consumed-data -changes do, and reused work does not count as current execution. Published records -follow the selected compatibility policy and preserve failure/usage distinctions. +**Completion evidence:** downstream failure/fix/retry reuses accepted predecessors; +message changes miss and settings-only changes can hit; corrected answers use the +initial key; hits make no model calls or fresh validation claims. Artifacts need +no metadata bundle. Machine output and debug capture obey the selected contracts, +including failures after publication and quiet-mode capture. -### Phase 6: Verify And Document The Core Cutover +### Phase 6: Verify And Document The Coordinated Cutover -- Complete the acceptance checks below and the removal inventory. Verify the - dependency graph contains no unused old-path PromptKit/ConfigKit or catalogs. -- Finish migration guidance, maintained examples, attribution, successor ADRs, - and canonical documentation updates. Reconcile affected future-work notes. -- Keep existing inspection commands usable with native reports. Document that - the standardized CommandKit command surface remains the subsequent phase. +- Complete the acceptance checks and removal inventory, including dependency + cleanup, maintained examples, and the assembled command surface. +- Finish release migration guidance, attribution, successor ADRs, and affected + canonical documentation. Reconcile future-work notes and notepad status. +- Confirm no compatibility scaffold, deferred CommandKit adoption, local hash + policy, or obsolete metadata requirement remains in the finished migration. -**Completion evidence:** the core native architecture, configuration migration, -checkpoint policy, diagnostics, and maintained offline workflows are verified; -remaining work is explicitly the CommandKit follow-up or separately identified -future work, not hidden adapter or retry compatibility machinery. - -### Phase 7: Adopt CommandKit Presentation - -- Resolve U10 and adopt CommandKit with ckconfig/ckprompt. Supply application and - engine loaders plus request builders for the selected diagnostic commands. -- Replace applicable Notarius-owned configuration/PromptKit commands and standard - presentation while preserving deliberate machine-output contracts and domain - outcome mapping. Keep provider smoke diagnostics explicitly opt-in. - -**Completion evidence:** standard commands use upstream integrations and the same -native source assembly as execution; application preflight and published receipts -retain their intended meaning. This phase completes the presentation target and -is not a prerequisite for completing the core PromptKit cutover. +**Completion evidence:** PromptKit, ConfigKit, and CommandKit adoption, accepted- +artifact reuse, artifact delivery, diagnostics, and maintained offline workflows +are verified together. Remaining work is explicitly separate future scope. +Release preparation/publication is governed separately by release policy. ## Removal Inventory | Retire or replace | Retained application responsibility | | --- | --- | -| `StructuredLLMClient`, private structured-completion request/response types, adapter conversions | Native request construction and typed domain interpretation. | -| Prompt/profile `AssetRegistry` plumbing, `PromptAssetManifest`, `ModulePromptFS`, synthetic shared mounts, manual fingerprint enumeration | Embedded content and module semantics; schema responsibilities resolved under U2. | -| `single_response_v1`, raw `ModelCandidate`/`SemanticCorrection`, manual replay, correction capability checks | Typed candidates, actionable findings, native exchanges, and assessment. | -| LLM retry portions of `runProducerAttempts` and `executeValidationChain`, module rerun directives | Ordered validators, acceptance/rejection/fallback policy, and useful provenance. | -| `Scheduler`, `scheduledClient`, `concurrency.total_llm`, worker coupling | Bounded pipeline work and native per-backend admission. | -| Broad configuration/prompt/catalog/implementation checkpoint fingerprints and invocation-wide lookup barriers | Logical work, consumed-input identity, load checks, and explicit recomputation. | -| Inspection wrappers, copied effective parameters, `LLMExecutionSummary` and usage conversions/accumulators, debug completion wrapper, redundant call IDs, adapter profile recorder | Native facts with application scope and selected durable projections. | -| Custom standard inspection commands/presentation in the CommandKit phase | Application loaders, request builders, report content, and outcome mapping. | +| `StructuredLLMClient`, private request/response types, adapter conversions | Native request construction and typed interpretation. | +| Prompt/profile `AssetRegistry`, `PromptAssetManifest`, `ModulePromptFS`, synthetic mounts, manual fingerprint enumeration | Embedded content and module meaning; schema choices under U2. | +| `single_response_v1`, raw `ModelCandidate`/`SemanticCorrection`, manual replay, correction capability checks | Typed candidates, actionable findings, native exchanges, assessment. | +| LLM retry loops in `runProducerAttempts`/`executeValidationChain`, module rerun directives | Ordered validators, domain acceptance/rejection/fallback. | +| `Scheduler`, `scheduledClient`, `concurrency.total_llm`, worker coupling | Bounded pipeline work and native backend admission. | +| Checkpoint stage/dependency/configuration fingerprints, invocation-wide barriers, manifests, acceptance/provenance envelopes | Small accepted-artifact cache using the upstream message hash, ordinary load checks, explicit controls. | +| Inspection wrappers, copied effective parameters, usage summaries/conversions/accumulators, debug completion wrapper, synthetic IDs, profile recorder | Native facts with application scope for diagnostics. | +| Custom dispatch/help/version/parsing, command-specific loading, copied inspection, legacy aliases/flags, parallel encoders and verbosity handling | Native declarations/loaders, pipeline handlers, domain input checks. | +| Mandatory run manifests, reporting-only metadata bundles, extensive receipts and durable execution ledgers | Domain artifact files, one small native completion report, optional debug evidence. | +| Summary/trace hierarchy, heuristic debug-content scrubbing, custom transcript/deduplication machinery | Convenient run/operation capture and native secret/credential omissions. | ## Acceptance And Verification -Use focused behavioral tests with real deterministic collaborators, a native -engine, and injected clients or a fake HTTP provider. Test domain interpretation -and assessment directly; pipeline tests can use fake stages. Replace tests that -preserve removed mechanics rather than reproducing a private LLM interface for -testing. Default tests remain offline and independent of real credentials. +Use real CommandKit, ConfigKit, and PromptKit in representative assembled flows +with a fake at the provider boundary. Keep the suite deterministic, offline, and +independent of real credentials. Test domain interpretation/assessment at their +package boundaries; use subprocess tests for streams, exit status, alias wiring, +and representative machine output. Do not duplicate upstream parser/renderer/ +retry tests or freeze complete help text and native debug snapshots. | Area | Required evidence | | --- | --- | -| Configuration and assets | Version 6/new resources work; legacy formats are rejected intentionally; main-relative companions and native imports work independently of working directory; peer conflicts fail; same-ID replacement affects only the intended default; ordering/cache controls and selected schema contracts survive assembly. | -| Preflight and inspection | Runtime, inspection, and preflight share effective definitions; unknown statically selected IDs and invalid definitions fail offline; partial profiles alone pass; completed target checks occur on concrete requests; actual-run overrides appear in provenance. | -| Native artifact workflow | Representative extraction and normalization produce typed candidates, invoke ordered validators, and preserve source/reference identity, safe plan application, artifact-schema checks, and stable output ordering. | -| Continuation and failures | Multiple turns accumulate history with fixed input/handle meanings; every revised candidate and final allowed response is assessed; native transport/structural exhaustion is not silently retried outside PromptKit; validator failure differs from rejection; selected safe fallback and cancellation policy hold. | -| Admission and workers | All roles share the selected backend pool; independent backends remain independent; pipeline work stays bounded; queue exhaustion, nested validators, and cancellation settle without leaked capacity or a retained global ceiling. | -| Checkpoints | Successful predecessors survive downstream fixes and prompt/model/validation-setting changes; changed prompt IDs or consumed source/reference/upstream data miss; recompute forces selected work/dependents; corrupt/incompatible or unaccepted/incomplete artifacts and ineligible derivatives are unusable; compatible schema changes do not require exact hash equality. | -| Reuse provenance | Original acceptance and execution provenance survive resume without new semantic validation claims or historical token usage counted as current; recording remains separate from reuse; canonical chunk-plan caching retains its distinct policy. | -| Execution records | Initial/continuation/nested validator accounting preserves terminal coverage and unknown-versus-zero usage without double counting; failures without a result remain observable; native success is distinct from acceptance; debug is opt-in and ordinary records exclude sensitive response/history content. | -| Published behavior | Maintained minimal and complete D&D workflows, session routing, artifact output, manifest/receipt compatibility, and selected migration diagnostics work through the assembled CLI. CommandKit-phase tests cover its own command/presentation changes. | +| Configuration/assets | Version 6/new resources work; old formats intentionally rejected; companions/native imports retain main-source context; peer conflicts fail; same-ID replacement and selected schemas work. | +| Commands/loaders | Required operands, native alias, supplied-value distinctions, references, and run-wide overrides reach intended handlers/roles; help/version/completion need no config; diff selections remain distinct. | +| Preflight/inspection | Same definitions across execution and inspection; missing statically selected resources fail with context; partial profiles alone pass; no provider calls, transcript, or credential requirement for offline preflight. | +| Domain workflow | Representative extraction and normalization preserve source/reference identity, fixed handles, safe plan application, ordered validators, artifact schemas, and stable output ordering. | +| Continuation/failures | Accumulated history, full revalidation and final-turn assessment; no blanket retries beyond native exhaustion; validator failure differs from rejection; selected fallback, incomplete-validation, and cancellation policy hold. | +| Admission/workers | Shared backend pools across roles, independent backends, bounded pipeline work, nested validators, queue exhaustion, and cancellation without leaked capacity or a global ceiling. | +| Accepted-artifact cache | Downstream recovery; initial-message keys; corrected final artifact stored late under the initial key; changed messages miss; settings/ID-only changes can hit; no model/revalidation on hits; unusable entries miss; failed/rejected/incomplete work and ineligible derivatives excluded; no required history. | +| Cache migration | Selected reuse/bypass/refresh and old-record treatment work; invocation configuration no longer blocks lookup; canonical chunk caching retains its distinct policy. | +| Output/outcomes | Artifact files independent of report format; native text/JSON/YAML summary and qualified outcomes; no mandatory metadata bundle; quiet suppression, verbose stderr, debug path; native nonzero failures and useful explanations. Publication survives later capture/report failure without model reruns. | +| Execution observations | Initial/continuation/validator totals preserve unknown-versus-zero usage without double counts; result-less failures observable; reuse does not count historical work; native execution success remains distinct from acceptance. | +| Debug controls/lifecycle | Default/CLI/config/explicit-empty paths and native mode ordering; quiet capture; allocation before engine/preflight; start-time relative `latest`, no completion retarget; disabled runs leave it untouched; capture failures preserve primary causes and publication facts. | +| Debug evidence | Available input/source/native snapshots, readable text, all visible turns, assessments, normalization and deterministic outputs, cache hits, and failed-run evidence; no invented provider transcript; ConfigKit secrets/native credentials omitted, no heuristic content scrubbing. | +| End-to-end migration | Maintained minimal and complete D&D workflows, session routing, reference behavior, raw artifacts, reports, and migration examples work through the new executable. No postponed CommandKit phase. | -Run focused checks while implementing and the repository-wide commands for the -completed application cutover, following the [testing policy](../policy/testing.md): +Run focused checks during implementation and the repository-wide checks for the +completed cutover under the [testing policy](../policy/testing.md): ```sh go test ./... @@ -521,47 +828,49 @@ go vet ./... go build ./cmd/notarius ``` -Check maintained examples, dependency removal, links, and attribution alongside -those commands. Live provider checks and human model-quality evaluation can -inform deployment and prompt refinement; they are not requirements of the -deterministic offline suite. Planning/documentation completion does not claim -that these implementation acceptance checks have already passed. +Check maintained examples, dependencies, attribution, documentation links, and +removal coverage. Live provider smoke and human model-quality evaluation remain +optional, outside the default suite. These migration checks add no permanent +release gates. Documentation completion does not claim that implementation +acceptance checks have passed. ## Migration Guidance And Documentation -Maintain examples that distinguish embedded-only operation from companion -configuration, using separate directories when needed. Explain moving/importing -old sources, qualified IDs, complete replacement versus inheritance, native local -backends, removed catalogs and prompt versions, and the separate application and -PromptKit source versions. Document worker/global-limit changes, retry-budget -migration, accumulated conversation costs, and the selected failure policy. +Provide practical release guidance for operators and subprocess callers: -Explain successful-work checkpoint reuse, explicit recomputation to apply prompt -or setting improvements, consumed-data misses, original validation provenance, -and the chosen old-record transition. Document changed inspection and durable -fields deliberately rather than promising incidental old adapter output. +- New commands/flags, native `run` alias, `--format`, stdout/stderr, outcomes, and + saving optional reports by redirection. No legacy CLI compatibility promise. +- Version 6 and native resources, embedded-only versus companion examples in + appropriate directories, imports, qualified IDs, replacement/inheritance, + native local backends, removed catalogs/versions, and separate source versions. +- Native admission and worker defaults, removed global limit, retry-budget + migration, accumulated-history costs, and selected role failure policy. +- Accepted-artifact caching, message-based misses, settings-only reuse, refresh/ + bypass for changed interpretation or validation, and old-checkpoint handling. +- Artifact delivery without mandatory manifests/receipts; preserve intrinsic + artifact schemas and document any explicitly selected format change. +- Debug root/default/empty behavior, `latest`, native mode ordering, failure + behavior, and ordinary operator responsibility for application data. -Update the canonical [configuration](../config.md), [CLI](../cli.md), +Update canonical [configuration](../config.md), [CLI](../cli.md), [operations](../operations.md), [internal overview](../internal/overview.md), [LLM](../internal/llm.md), [pipeline](../internal/pipeline.md), [modules](../internal/modules.md), [state](../internal/state.md), and affected -integration/consumer guides when their behavior changes. Update the -[architecture policy](../policy/architecture.md) to make native PromptKit an -explicit execution dependency and remove the superseded scheduler, retry, -asset-registration, and fingerprint constraints. +integration/consumer guides as behavior lands. Remove superseded manifest/receipt +contracts then; keep current-behavior documentation accurate until implementation. +Update [architecture policy](../policy/architecture.md) for native dependencies +and changed scheduler, retry, asset, cache, and reporting boundaries. -Record significant ownership and contract changes in successor ADRs, including -those affecting [asset assembly](../adr/0011-centralize-llm-assets.md), +Record significant changes in successor ADRs, including +[asset assembly](../adr/0011-centralize-llm-assets.md), [validation retries](../adr/0014-feedback-aware-validation-retries.md), -[module-requested retries](../adr/0016-feedback-aware-module-requested-retries.md), -and [PromptKit configuration](../adr/0019-adopt-native-promptkit-configuration.md). -Also record the changed admission and checkpoint matching decisions. Preserve -accepted decision text and update supersession status as appropriate under the -[documentation policy](../policy/documentation.md#architecture-decision-records). -The discussion record supplies rationale and evidence; this roadmap tracks -implementation status until the corresponding behavior lands. +[module retries](../adr/0016-feedback-aware-module-requested-retries.md), +[PromptKit configuration](../adr/0019-adopt-native-promptkit-configuration.md), +admission, caching, and CLI/reporting ownership. Preserve accepted decision text +and update supersession status under [documentation policy](../policy/documentation.md#architecture-decision-records). +Notepads retain discussion history; this roadmap owns implementation status. -[release]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.2/docs/releases/v0.23.2.md -[migration]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.2/docs/consumers/configuration-migration.md -[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.2/docs/formats.md -[consumer]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.2/docs/consumers/pkg-promptkit.md +[release]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.3/docs/releases/v0.23.3.md +[migration]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.3/docs/consumers/configuration-migration.md +[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.3/docs/formats.md +[consumer]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.3/docs/consumers/pkg-promptkit.md