From 857c0bae201bb5f9b5ffdcb20c4f5a0bddb00114 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 20 Nov 2026 15:16:33 +0000 Subject: [PATCH] Retire completed roadmaps and preserve future work --- ...t-commandkit-native-operator-interfaces.md | 5 +- docs/policy/architecture.md | 7 +- docs/roadmap/commandkit-adoption.md | 367 -------- docs/roadmap/commandkit-notepad.md | 331 ------- docs/roadmap/future.md | 27 + docs/roadmap/implementation.md | 816 ------------------ docs/roadmap/narratio-feature-request.md | 168 ---- docs/roadmap/policy.md | 223 ----- docs/roadmap/promptkit-v0.9.0-adoption.md | 352 -------- docs/roadmap/promptkit.md | 374 -------- docs/roadmap/upgrade-kit.md | 274 ------ 11 files changed, 34 insertions(+), 2910 deletions(-) delete mode 100644 docs/roadmap/commandkit-adoption.md delete mode 100644 docs/roadmap/commandkit-notepad.md create mode 100644 docs/roadmap/future.md delete mode 100644 docs/roadmap/implementation.md delete mode 100644 docs/roadmap/narratio-feature-request.md delete mode 100644 docs/roadmap/policy.md delete mode 100644 docs/roadmap/promptkit-v0.9.0-adoption.md delete mode 100644 docs/roadmap/promptkit.md delete mode 100644 docs/roadmap/upgrade-kit.md diff --git a/docs/adr/0006-adopt-commandkit-native-operator-interfaces.md b/docs/adr/0006-adopt-commandkit-native-operator-interfaces.md index 8751d18..ce204dd 100644 --- a/docs/adr/0006-adopt-commandkit-native-operator-interfaces.md +++ b/docs/adr/0006-adopt-commandkit-native-operator-interfaces.md @@ -49,5 +49,6 @@ instead. Standard inspection exposes the upstream result without constructing a different effective document, reconciling separate explanation trees, or reinterpreting -upstream paths. The [adoption roadmap](../roadmap/commandkit-adoption.md) tracks -implementation. +upstream paths. The completed +[adoption record](https://forge.maximumdirect.net/eric/scriptorium/src/commit/f5573f7c8f2ddf0d69414a05c978c8d6cfe291e7/docs/roadmap/commandkit-adoption.md) +remains in Git history. diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 3431346..c9aa68e 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -2,7 +2,7 @@ **Base Policy Version:** 1.3 -**Last Updated**: 2026-11-19 +**Last Updated**: 2026-11-20 **Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/architecture.md @@ -75,8 +75,9 @@ neutrally expose upstream features and semantics. CommandKit owns shared command parsing, presentation, and outcome mechanics; application commands and effects remain local. Standard configuration inspection uses native adapters without custom effective documents or evidence reconciliation. This decision complements -ADRs 0004 and 0005; the [adoption roadmap](../roadmap/commandkit-adoption.md) -records the implementation work. +ADRs 0004 and 0005; the completed +[adoption record](https://forge.maximumdirect.net/eric/scriptorium/src/commit/f5573f7c8f2ddf0d69414a05c978c8d6cfe291e7/docs/roadmap/commandkit-adoption.md) +remains in Git history. The CLI exposes Promptkit's captured framework configuration inspection. Its `show` and `explain` reports use Promptkit's native redaction for classified diff --git a/docs/roadmap/commandkit-adoption.md b/docs/roadmap/commandkit-adoption.md deleted file mode 100644 index e76976d..0000000 --- a/docs/roadmap/commandkit-adoption.md +++ /dev/null @@ -1,367 +0,0 @@ -# CommandKit Adoption - -## Status And Intent - -Implementation and assembled acceptance verification are complete; see the -[implementation plan](implementation.md) for evidence and selected releases. -Initial roadmap prepared 2026-11-19. This document owns the target and product intent, -incorporating the decisions in the [migration notepad](commandkit-notepad.md). -The notepad remains the discussion -record. The [Narratio proposal](narratio-feature-request.md) supplies consumer -acceptance scenarios for requirements discovery. The -[implementation plan](implementation.md) owns the ordered stages and concrete -adapter choices. - -[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md) records -the native-interface adoption and ownership boundaries, complementing ADRs 0004 -and 0005. - -Make Scriptorium a CommandKit-native executable interface over PromptKit, -including ckconfig and ckprompt. Most subprocess consumers should be able to -select a stored prompt and consume its resulting artifact directly. Operators -and consumers needing inspection or metadata should use native upstream -interfaces and reports. - -This is a full CLI cutover. Existing command names, flag spellings, parsing, -report shapes, and exit conventions are not compatibility constraints. Release -migration guidance replaces a compatibility layer. Implementation may proceed -in reviewable increments; this does not require shipping both interfaces. - -## Planning Baseline And Upstream References - -Reviewed Scriptorium baseline: `5f32a4f2adb2d382a6cfce3a787ada4576be7705`. -At that baseline the module used Go 1.27.0, PromptKit v0.23.3, and ConfigKit -v1.2.1, without CommandKit. The following table records the starting point. - -| Baseline implementation | Migration work | -| --- | --- | -| `internal/adapter/cli` dispatches and parses commands, resolves configuration, builds engines and requests, writes diagnostics, and returns integer statuses. | Replace dispatch and shared CLI mechanics with CommandKit; retain application loading, request mapping, and effects through its extension points. | -| `run` uses flag-based prompt selection and writes generated content; `--execution-report` writes an observer-derived Scriptorium report. | Adopt positional prompt selection, native request flags, and native result reporting. | -| `render`, `inspect prompt`, and `inspect profile` use custom presentation in `internal/format`. | Replace with native ckprompt operations and remove unused presentation code. | -| `config` and `inspect configuration` separately expose application and framework configuration. | Install one ckconfig family with `app` and `promptkit` scopes, including comparison. | -| `internal/config` owns application schema, discovery, defaults, and conversion through ConfigKit. | Adapt its loader and explicit overrides to standard selections and scope capabilities. | -| `serve` constructs a restricted HTTP artifact reader and one shared PromptKit engine. | Register it as an application command and preserve existing HTTP behavior. | -| `internal/report` also supplies HTTP's optional execution report. | Remove its superseded CLI use; retain functionality still used by HTTP. | - -The [current CLI](../cli.md), [configuration contract](../config.md), -[adapter internals](../internal/adapters.md), and -[subprocess contract](../integrations/subprocess.md) now describe the implemented -native interface, not the historical starting point or a compatibility layer. - -The reviewed upstream combination is CommandKit v0.7.0, ckconfig v0.9.0, -and ckprompt v0.10.0, documented at revision -`d330d7637f2e7507eca931a899397222c82bc892`: - -- [Consumer guide][upstream-guide]: composition, loading, reusable bindings, - reporting, and outcomes. -- [CLI reference][upstream-cli]: native command grammar and observable behavior. - -The selected released combination retains Scriptorium's adopted PromptKit -v0.23.3 fixes and ConfigKit v1.2.1. The reviewed ckprompt release's PromptKit -v0.23.2 minimum does not require a downgrade. Supported public APIs and released -dependencies remain subject to the existing -[architecture policy](../policy/architecture.md). - -No selected-format accessor is required for this migration. The native -invocation reporter handles the main result on stdout; the existing writer API -handles the separate report with automatic or explicitly selected rendering. -The upstream accessor proposal remains optional API work, independent of -Scriptorium's adoption. - -## Target End State - -### Responsibilities And Scope - -CommandKit owns command declarations, dispatch, common parsing, help, reporting, -and outcome mechanics. ckconfig and ckprompt supply their standard families. -ConfigKit owns configuration policy through the fully resolved handoff, -including resolution of PromptKit's configuration using PromptKit's schema and -rules. PromptKit owns definition, preparation, execution, validation, and -inspection semantics. Scriptorium owns the application domain: it interprets -resolved values and uses upstream APIs and results to satisfy user requests. -Application commands, process lifecycle, and artifact delivery remain local. - -This preserves Scriptorium's request-independent execution model and support -for valid definitions under [ADR 0004](../adr/0004-definition-boundary.md). -It adds no workflow, conversation, archive, or resume system. HTTP design review -remains separate work before v1.0; migrating its startup command does not -redesign the HTTP API or its execution-report representation. - -Use shared upstream capabilities where available. A concrete missing shared -capability should prompt an upstream discussion before a local substitute. -Application-specific loading and effects remain ordinary application work. - -### Command Surface - -| Surface | Target | -| --- | --- | -| Generation | Application command `run PROMPT_ID`, with a required positional prompt ID and no duplicate prompt flag. | -| HTTP service | Application command `serve`. | -| Configuration | Native `config` family with `app` and `promptkit` scopes: scope discovery, validation, effective values, sources, explanations, and diff. | -| Resource inspection | Native prompt, profile, backend, namespace, and collection inventories and applicable named inspection. | -| Dependency discovery | Native `promptkit requirements show PROMPT_ID`. | -| Concrete validation | Native `promptkit requirements validate` capability. | -| Prepared preview | Native `promptkit show prepared PROMPT_ID`, replacing `render`. | -| Provider diagnostics | Native smoke-test commands, invoked explicitly. | -| Executable support | Native help, version, reporting modes, outcomes, and shell completion. | - -Install application commands outside the reserved standard families. Enable -the native convenience aliases consistently. Prefer shorter spellings such as -`--profile`, `--input-file`, `--input-text`, and `--var` in examples and guidance -where applicable and unambiguous; canonical `--llm-*` spellings remain available. -Aliases retain upstream semantics: `--input` supplies literal text, and file -references use `--input-file`. - -Reuse applicable ckprompt resource, input, and execution bindings for `run`. -Preserve explicit-value presence, including zero and empty values, and native -repeated mapping semantics. Do not carry forward comma splitting or obsolete -aliases merely because the old parser accepted them. Keep application-only -controls, including HTTP settings, reporting, and whole-operation deadlines, -distinct from framework request controls. - -Completion initially uses native command, flag, static-value, and path -completion, with suitable application hints. Dynamic installed-resource -completion is not required. Smoke tests are explicit operator operations; -their inclusion does not make provider access a startup or release prerequisite. -Preserve native diagnostic findings, including successful invocations whose -reports describe unsupported or unsuccessful checks. - -### Configuration Authority And Native Inspection - -The migration implements the ownership decision in -[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md) through -these two boundaries: - -1. **ConfigKit's completed result is authoritative configuration.** Scriptorium - supplies its schema, domain defaults, validation, and genuine application - configuration-resolution logic through ConfigKit's supported extension - points. Those callbacks operate within ConfigKit's lifecycle and evidence - model, including recording resolution changes through the supported APIs. - Scriptorium consumes the completed result without subsequently revising what - effective configuration means. Runtime conversion and request construction - may consume resolved values; they do not introduce another configuration - merge, defaulting, or normalization pass. This follows the configuration - boundary established in [ADR 0005](../adr/0005-configkit-boundary.md). -2. **Standard inspection exposes that result through native adapters.** - Scriptorium selects and acquires the requested configuration and declares - supported capabilities. Use `ckconfig.FromConfigKit` for the application - result and `ckprompt.ConfigScope` for PromptKit's captured configuration - inspection within the native `ckconfig` family. Scriptorium does not assemble - a different effective document, reconcile separate explanation trees, or - reinterpret upstream path semantics. Effective values, sources, explanations, - metadata, and comparisons come from the acquired upstream result through - those adapters. CommandKit owns their standard presentation. - -Application selection and supported configuration overrides feed the loading -lifecycle before its completed result is exposed. Adapting loaders or supplying -scopes below does not authorize a second configuration-resolution or inspection -model. The `app` and `promptkit` scopes retain their respective upstream evidence; -they are not combined into a synthetic effective configuration. - -### Configuration, Collections, And Request Context - -Expose application configuration through `app` and captured framework -configuration through `promptkit`. Collections are resources within the -framework configuration, not separate configuration scopes. Application-only -inspection must work without constructing a PromptKit engine. - -`--config` selects Scriptorium application configuration on every applicable -command, including framework inspection. That configuration selects framework -sources. Adopt native `--overlay` selection and upstream selection presence -semantics. For ConfigKit v1.2.1 the supplied value selects an overlay by name, -not an arbitrary file path. Map selections through the application's ConfigKit -loader rather than retaining the old flag parser as a compatibility layer. -Keep HTTP-related named flags on `serve`. The `config` family exposes only -upstream commands and flags: add no application selectors or custom -`--against-*` flags. Retain native `--against-config`, `--against-overlay`, and -`--against-set` where supported. Remove `--promptkit-source` and `--schema-dir` -from all commands. Native resource IDs select loaded prompts and profiles; -installation configuration supplies their definitions and schema source. - -For implicit application configuration discovery, adopt ConfigKit's built-in -directory presets and their native filename conventions through `SearchConfig`. -Replace the legacy two-file search. The selected order is `WorkingDirectory`, -`UserConfigDirectory`, `HomeDirectory`, then `UnixSystemDirectories`, using each preset's native -filename rules. This implements current-directory, user, then system discovery; -the two user presets cover the platform configuration directory and home layout. -ConfigKit selects one main file, with native optional-search exhaustion and -selected-file error behavior; this is not a merge of all discovered files. - -Enable temporary configuration overrides where the loader supports them, -passing native override records into loading. ConfigKit owns rejection and -diagnostics for duplicate or ancestor/descendant-overlapping records. Do not -filter or merge conflicts locally. -The reviewed PromptKit scope does not support these overrides; do not emulate -them locally. Configuration comparison must support independent selections for -both sides in both scopes through native flags alone. - -Use an application `promptkit` settings section containing `configuration`, the -path to one external framework entry file, and `schema_dir`, the output-schema -root. Replace the general `promptkit_sources` file/directory list and top-level -`schema_dir`. Pass the selected file to PromptKit as its native main input with -ConfigKit imports enabled. Keep the bundled upstream defaults. - -Keep the established collection-discovery model: that entry file's ConfigKit -glob imports discover `collection.yml` and `collection.yaml` entry points; each independently -maintained collection declares its namespace and imports its own definitions -through relative references. Retain the -[discovery example](../../examples/config.discovery.yml) and representative -multi-definition collection documentation, updating the application example to -the new settings. No repeated source flag, separate directory-source mechanism, -Git update manager, or custom collection traversal is part of this migration. - -Embedding actual PromptKit definitions under the application's `promptkit` key -is deferred pending suitable upstream support. The current section contains -application settings for acquiring the separate framework document. Do not -extract, reserialize, or reload a resolved application subtree as a substitute -for a native upstream handoff. This deferred capability does not block adoption. - -Use native prompt, profile, and backend namespace selectors independently on -applicable commands. Short caller-supplied IDs use their selected namespace; -qualified IDs remain exact. Selection does not rewrite stored references. -Retain upstream inventory filters and defaults, including `--all-namespaces`. -Do not add a configurable default namespace in this migration. - -Share applicable configuration selection, engine loading, and request mapping -across execution, preview, validation, and discovery. Preserve each operation's -upstream lifecycle: discovery can work before artifacts exist; preparation -loads and renders without generation. This is consistency of selection and -mapping, not a promise that separate invocations see an immutable snapshot. - -### Generation, Reports, And Process Outcomes - -Use a main CommandKit `Report` whose value is PromptKit's native `RunResult` and -whose text template emits only the resulting artifact content. The template -should emit artifact bytes without presentation decoration. Default/text serves raw -artifact consumers; JSON and YAML expose the full native result. The native -structured serialization, including its representation of artifact bytes, -remains upstream-owned. There is no Scriptorium result envelope. - -| Selection | Behavior | -| --- | --- | -| Main result | Goes through the native invocation reporter to stdout using the selected format. | -| `--format text` or default | Main result contains only the artifact. | -| `--format json` or `--format yaml` | Main result contains the native result and metadata. | -| `--report PATH` | Additionally write the native result through CommandKit's renderer, independently of the main format and destination. Without `--report-format`, use native automatic rendering. | -| `--report-format text\|yaml\|json` | Explicitly select the separate report's native rendering format. | - -The separate report contains the same native `RunResult`, without the main -report's artifact-only text template. Omission of `--report-format` leaves the -format unset so CommandKit decides how to render it. Its current automatic -rendering for structured values is YAML; future upstream default changes flow -through. Scriptorium does not set a default report format. - -There is no `--output` or legacy `--out` flag. Callers save the main result by -redirecting stdout in a shell or supplying a file as the subprocess stdout -destination. Diagnostics remain on stderr. Callers wanting main output omit -`--quiet`, including when stdout is redirected. Filename extensions do not -select formats. The separate report includes the native result's content as -well as metadata; it replaces the CLI's old -observer-derived metadata projection. A caller wanting an artifact file plus -metadata redirects stdout and selects a separate `--report` path. The caller -manages redirected destinations and retention; there is no automatic reporting -directory or report collection. - -Native result reporting is available when PromptKit returns a result. -Operational errors return nonzero status and native failure diagnostics, without -synthesizing replacement results. Preserve PromptKit's distinction between a -completed content check reporting `ValidationFailed` and an operational failure -to perform the check. Neither extra content judgments nor a structured JSON -invocation-error envelope is part of this migration. - -Adopt CommandKit's quiet and verbosity semantics, including rendering and -presentation failures. Console results use the invocation reporter; diagnostics -use its diagnostic channel. `--verbose` preserves the selected stdout result -and exposes emitted Info and Warning messages on stderr under native rules. -An explicit `--report` write is an application -effect rendered through the writer API and still occurs in quiet mode. -Quiet does not cancel generation; it suppresses the main result even when -stdout is redirected, while failure explanations remain visible. Move any -retained generation summary into an appropriate native message category. - -Map typed upstream failures and configuration diagnostics into native outcomes, -without parsing error text. Standard statuses remain upstream-owned. Use an -application domain outcome for completed validation failure, distinct from -usage and diff-check outcomes. The implementation plan specifies the mapping. -Delivery failures must produce a nonzero outcome and explanation, preserving -native presentation-failure behavior where applicable, including an already -nonzero domain outcome. Requested file errors must not disappear merely because -they occur outside the invocation reporter. - -For `--report`, use ordinary file replacement without creating parents. Attempt -the main output followed by the report, and attempt the report even if main -delivery fails. Open the report only when a native result exists. Redirection -and its file-creation or truncation behavior belong to the caller. Scriptorium -does not manage the main output file or check it against the report path. This -adds no rollback or transactional delivery; written bytes may remain after -failure. - -Wire signal cancellation through the invocation context. Keep the application -whole-operation budget separate from the native per-attempt timeout binding. -Use `--run-timeout` with Go duration values mapped to PromptKit's -`OperationTimeout`, preserving upstream zero, negative-value, and timeout -behavior without a second timeout policy. - -### Preview And Consumer Inspection - -Remove `render`, its compatibility aliases, `defaults.render_format`, and -unused prepared-output formatters. Native prepared preview uses its upstream -report, default/text YAML presentation, standard formats, request flags, -diagnostics, and outcomes. It does not call a model. Consumers save preview -output through stdout capture or redirection, as they do for generation. - -Adopt native inspection reports, including captured prompt messages and rendered -prepared content, without recreating old summary projections. Native schemas -and adopted upstream versions govern structured output; this migration adds no -separate schema-version wrapper or compatibility guarantee. - -Implement the [Narratio acceptance scenarios](narratio-feature-request.md#consumer-acceptance-scenarios). -Requirements discovery exposes native classification, completeness, and issue -codes. Complete discovery is distinct from satisfied bindings and execution -readiness; partial discovery can succeed with status zero. Narratio owns its -pipeline, binding graph, and policy for incomplete findings. Preserve native -metadata without inventing prompt versions, variable defaults, or input schemas. - -## Acceptance And Scope Boundaries - -The target is met when Scriptorium exposes the native command surface and -application behavior above, superseded CLI machinery is retired, and maintained -documentation and examples describe the shipped interface. In particular: - -- Configuration callbacks, runtime consumers, and native inspection agree on - ConfigKit's completed values and evidence. Application-only inspection needs - no PromptKit engine, and comparison sides retain independent selections. -- Applicable selection and request context remain consistent across execution, - preparation, discovery, and inspection of multiple independently maintained - collections. Their upstream lifecycle differences remain visible. -- Generation defaults to the artifact alone; structured output and separate - reports expose the native result. Main output uses stdout and native quiet - semantics; the optional report file uses native automatic or explicitly - selected rendering, independently of quiet, with useful failure outcomes and - nontransactional delivery. -- Narratio's linked acceptance scenarios are supported, including useful partial - discovery and discovery before generated artifacts exist. -- Native help, aliases, completion, and explicit smoke testing are available. - Including smoke testing adds no provider access prerequisite to startup or - release validation. -- Server startup reaches the existing HTTP adapter with its transport, - restricted-reading, execution-report, and shared-capacity behavior intact. -- Canonical contracts, examples, dependency attribution, and migration guidance - reflect the cutover. The CLI migration includes positional prompt selection, - command replacements, literal versus file inputs, repeated mappings, overlay - selection, native endpoint/timeout controls, stdout redirection in place of - output-file flags, content-bearing reports, optional report-format selection, - report availability, quiet behavior, and changed exit statuses. - -The [implementation plan](implementation.md) owns task sequencing, concrete -adapter mappings, verification steps, and sprint status. The discovery and -source/schema decisions are settled. Neither the selected-format accessor nor -embedded framework configuration is a migration prerequisite. - -The [release policy](../policy/release.md#versioning-and-compatibility) governs -the eventual breaking release version. This migration does not itself select -or publish a release, introduce a compatibility layer, or settle the separate -pre-v1.0 HTTP design review. - -[upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md -[upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md deleted file mode 100644 index 2e5741b..0000000 --- a/docs/roadmap/commandkit-notepad.md +++ /dev/null @@ -1,331 +0,0 @@ -# CommandKit migration notepad - -Status: discussion record incorporated into the -[adoption roadmap](commandkit-adoption.md) and -[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md). -The roadmap owns implementation work; the ADR records the ownership decision. - -## Product context - -Scriptorium is a neutral executable interface over PromptKit. Its primary -consumers are applications that need to run stored prompts and consume their -output without importing PromptKit or building an internal prompting workflow. -The CLI and its subprocess contract are therefore central to this migration. - -An installation may load many independently maintained collections. The -existing collection model remains the starting point: ConfigKit imports discover -`collection.yml` or `collection.yaml` entry points, each collection declares its -own namespace, and relative imports assemble its profiles and prompts. See the -[configuration contract](../config.md) and -[discovery example](../../examples/config.discovery.yml). - -HTTP remains secondary to the CLI discussion. A broader HTTP design review is -planned before v1.0; adopting CommandKit does not itself settle that design. - -## Agreed direction - -### Full native cutover - -Decision recorded 2026-11-19: become a CommandKit-native application, including -`ckconfig` and `ckprompt`, and adopt upstream public conventions and -recommendations as fully as possible. - -Backward compatibility with existing CLI conventions is an explicit non-goal. -Legacy command names, flag spellings, parsing rules, report shapes, and exit -semantics do not constrain the new interface. Do not add compatibility wrappers, -legacy aliases, or duplicate inspection implementations solely to preserve the -old CLI. Adopt upstream convenience aliases as described below. - -Provide migration guidance in release documentation so consumers can update -their invocations and output handling. Guidance replaces a compatibility layer; -it does not require a transition period with both interfaces. The -[release policy](../policy/release.md#versioning-and-compatibility) governs -release version selection and documentation of breaking changes. - -### Ownership and integration - -Use CommandKit for command declarations, parsing, help, reporting, and outcomes; -use `ckconfig` and `ckprompt` for their standardized operator interfaces. -Scriptorium should retire the corresponding custom inspection machinery as -those interfaces take over. - -ConfigKit owns configuration policy through the fully resolved handoff, -including PromptKit configuration resolution. PromptKit owns prompting and -inspection semantics. Scriptorium interprets resolved values and uses upstream -APIs and results to satisfy user requests. CommandKit adoption does not introduce -workflow or conversation state. ADR 0006 records these boundaries. - -Prefer shared upstream capabilities over new Scriptorium-specific equivalents. -If a required shared capability is missing, discuss an upstream request before -designing a local substitute. Application-specific behavior still belongs in -Scriptorium. - -### Initial capability set - -Decision recorded 2026-11-19: include configuration comparison, provider smoke -tests, and shell completion in the initial migration, alongside application and -PromptKit configuration scopes, resource inventories and inspection, -requirements discovery, concrete request validation, and prepared-request -preview. - -Use the existing upstream capabilities. Configuration comparison should cover -both application and PromptKit scopes, with independent selections for each -side. Provider smoke tests run when explicitly invoked; including them does not -make them startup checks or release prerequisites. Document provider usage and -the distinction between successful diagnostic execution and positive findings. -Shell completion should use upstream command, flag, static-value, and path -completion, with appropriate hints for application-owned inputs. Dynamic -completion of installed resource names is a separate possible enhancement. - -Application-specific wiring remains to be designed, but inclusion of these -capabilities is settled. The prepared-request preview decision is recorded below. - -### Generation and subprocess requirements - -Decision recorded 2026-11-19: optimize the default generation response for the -majority of consumers, who want only the raw resulting artifact. Metadata is -optional and available through the native result reporting choices below. - -Prefer native CommandKit reporting and PromptKit result types before introducing -a Scriptorium-specific response format. A failure must produce a nonzero process -status and information explaining the failure. This does not require a new -structured error envelope: native diagnostics are an acceptable way to deliver -that information. - -Scriptorium remains a neutral interface to PromptKit. Pass through the errors, -validation outcomes, and result information that PromptKit supplies rather than -adding independent judgments about generated content or redefining upstream -failure semantics. Adapting those outcomes to CommandKit and process exit codes -is application work; deciding what constitutes a PromptKit failure is not. - -### Native result reporting and separate report files - -Decision revised 2026-11-19: use a main CommandKit `Report` containing PromptKit's -native `RunResult`, with a text template that emits only generated content. -Default/text output serves artifact consumers; standard JSON/YAML formats expose -the native result and its metadata. This composes existing upstream APIs; -ckprompt does not supply a general generation command or prescribe this template. - -Include an optional `--report PATH` flag requiring an explicit file destination. -Omitting it creates no separate report file. When requested, pass the native -`RunResult` to CommandKit's renderer without an artifact-only text template. -Optional `--report-format text|yaml|json` selects the native rendering format. -When omitted, leave the format unset and let CommandKit choose; its current -structured-value default is YAML, and future upstream changes flow through. -There is no Scriptorium default or filename-based selection. Report rendering -is independent of the main result's `--format`, representation, and destination. -Failure to write a requested report is a delivery failure and must produce a -nonzero outcome and diagnostic. - -Do not include a configured reporting directory or automatic report collection -in the initial migration. The caller selects the report path and manages its -lifecycle. A configured directory may be considered later if automatic -collection becomes useful; an explicit report path would take precedence. - -Native result reports are available when PromptKit returns a result. Operational -failures produce a nonzero exit and native diagnostics. This follows PromptKit's -capabilities and is the intended boundary, not a gap for Scriptorium to address. -Do not synthesize replacement results or add an alternative failure-report -format to compensate for the absence of a native result. - -### Output destinations and verbosity - -Decision revised 2026-11-19: remove the previously selected `--output` flag. -The main result uses the native invocation reporter and stdout. Callers save it -through shell redirection or a subprocess stdout destination; diagnostics remain -on stderr. Do not retain the old `--out` flag. - -`--format` selects the stdout representation independently of redirection: -default/text emits the raw artifact, while JSON/YAML emits the native result -with metadata. The filename does not select the format. `--report PATH` remains -an additional native result report, so callers can save the raw artifact and its -report to separate files by redirecting stdout and supplying `--report`. - -Adopt CommandKit's upstream verbosity and `--quiet` semantics fully, including -mode selection, message visibility, rendering, and presentation failures. Do -not add Scriptorium-specific exceptions to normal command-output suppression. -Quiet mode does not cancel generation, and failure explanations remain visible -through the native diagnostic channel. - -An explicit `--report` write remains an application-owned effect in quiet mode, -using the existing writer API. Quiet suppresses the main result even when stdout -is redirected; callers wanting that result omit quiet. No -selected-format accessor is needed, so the upstream proposal is no longer a -migration prerequisite. The [upstream reporting contract][upstream-cli] owns the -shared verbosity rules. - -### Prepared-request preview - -Decision recorded 2026-11-19: replace `render` entirely with the native -`promptkit show prepared PROMPT_ID` command, enabled through ckprompt's request -preparation integration. Remove `render` without a compatibility alias. - -Use the native prepared-run report, standard request flags, diagnostics, -verbosity, and outcomes. Default and explicit text output use the upstream YAML -presentation; JSON remains available through `--format json`. Remove -`defaults.render_format` and any custom prepared-output formatting code left -unused by the migration. - -Share application configuration selection, collection loading, and applicable -request construction with generation so previews describe the corresponding -execution request. PromptKit continues to own preparation semantics. - -Use the native result stream for preview output; consumers can capture or -redirect stdout to save it, as with generation. File-output convenience does -not justify retaining a separate preview command. Update maintained examples -and release migration guidance to use `promptkit show prepared`. - -### Configuration selection and namespaces - -Decision recorded 2026-11-19: fully adopt native configuration and namespace -conventions. Expose the `app` and `promptkit` configuration scopes through -ckconfig. `app` inspects Scriptorium's application settings; `promptkit` -inspects the framework configuration assembled from the selected sources. -Collections do not become separate configuration scopes. Application-only -inspection must not require constructing a PromptKit engine. - -`--config` consistently selects Scriptorium's application configuration, -including when inspecting the `promptkit` scope. That configuration selects -the framework sources and collection-discovery file. Adopt the standard -`--overlay` spelling and use consistent source-selection and loading rules -across generation, preview, inspection, requirements, and other applicable -commands. Keep the established ConfigKit collection-import model. - -Enable the native prompt, profile, and backend namespace selectors on -applicable commands. They independently scope short caller-supplied resource -IDs; qualified IDs remain exact selections. Namespace selection does not -rewrite stored references or change collection discovery. Keep configuration -scope, resource namespace, and profile selection distinct. - -Use native inventory filters, including namespace selection and -`--all-namespaces`, and retain upstream default listing behavior. Support -standard temporary configuration overrides where the upstream loader supports -them. The reviewed PromptKit configuration scope does not support those -overrides; do not add local override semantics to compensate. - -Do not add configurable default namespaces in the initial migration. Use -qualified IDs and explicit namespace flags when selecting namespaced resources, -while retaining upstream behavior for unqualified IDs. Configurable defaults -can be considered later if a need arises. - -### Native inspection reports and consumer requirements - -Decision recorded 2026-11-19: adopt native inspection reports and the native -`promptkit requirements show` interface for Narratio's early dependency -discovery. Its consumer needs and acceptance scenarios are recorded in the -[aligned Narratio proposal](narratio-feature-request.md). This direction is -accepted; Scriptorium integration remains to be implemented. - -Consume native report fields without a Scriptorium-specific schema-version -envelope. Use native nonzero outcomes and diagnostics for invocation failures; -JSON report selection does not require JSON errors. Neither a separately -versioned envelope nor programmatic invocation-failure categories blocks this -migration. A future concrete need for either belongs in an upstream discussion. - -PromptKit owns requirement classification, discovery completeness, and structured -discovery issues. Completeness is distinct from satisfied bindings or execution -readiness; Narratio owns comparison against its planned inputs. Keep early -discovery separate from concrete request validation. Use current exact resource -identities and native input/variable metadata, without restoring obsolete prompt -versions or inventing input schemas or variable-default semantics. - -Standard prompt inspection includes captured messages; prepared preview includes -rendered content. Adopt these native reports without rebuilding Scriptorium's -previous summary projections, and explain the changed presentation in migration -guidance. Requirements discovery retains its distinct upstream content boundary. - -### Application commands and standard request flags - -Decision recorded 2026-11-19: use `run PROMPT_ID` for generation, with the prompt -as a required positional operand and no duplicate prompt-selection flag. Keep -`serve` as the application command for the HTTP service. Both are CommandKit -commands owned by Scriptorium, outside the reserved `config` and `promptkit` -families. The CLI migration does not redesign the HTTP API. - -Reuse ckprompt's applicable resource, input, and execution flag bindings. -Preserve native parsing, explicit-value presence, repeated mapping semantics, -and PromptKit's interpretation of request values. Keep application-specific -configuration/source selection, `--report`/`--report-format`, server options, -and the whole-operation deadline separate from framework request controls. - -Enable upstream convenience aliases consistently on applicable commands, -including `run`. Prefer their shorter spellings in user-facing documentation, -examples, migration guidance, and subprocess integration examples wherever they -are applicable and unambiguous. For example, prefer `--profile`, `--input-file`, -`--input-text`, and `--var` over their `--llm-*` equivalents. Canonical upstream -spellings remain available with identical semantics; the preference does not -remove or rename them. - -Aliases retain upstream meanings. In particular, `--input` supplies literal -text; file references use `--input-file`. Migration guidance must explain this -change along with endpoint and timeout naming and repeated mapping values. -Use the canonical spelling where a shorter alias would be ambiguous; do not -assign an upstream alias a different application-specific meaning. - -## Upstream baseline - -The initial review covered CommandKit **v0.7.0**, ckconfig **v0.9.0**, and -ckprompt **v0.10.0**. These are a review baseline, not a final dependency choice -for implementation. The [upstream consumer guide][upstream-guide] describes -their composition and supported extension points. - -| Component | Relevant capabilities | -| --- | --- | -| CommandKit | Typed flags and operands with explicit-value presence, generated help and version, shared reporting and outcomes, optional shell completion. | -| ckconfig | Configuration scopes; validation, effective values, sources, explanations, and comparisons; temporary overrides where supported by the loader. | -| ckprompt | Prompt, profile, backend, namespace, and collection inventories; resource inspection; requirements discovery; optional concrete request validation, prepared-request previews, and provider smoke tests. Reusable request flags also serve application-owned commands. | - -Scriptorium currently uses PromptKit v0.23.3 and ConfigKit v1.2.1. The reviewed -ckprompt release declares PromptKit v0.23.2 and ConfigKit v1.2.1. Validate the -chosen dependency combination while retaining Scriptorium's adopted PromptKit -fixes; the older declared minimum is not a reason to downgrade. - -The [upstream CLI reference][upstream-cli] owns the detailed conventions. The -[current Scriptorium CLI](../cli.md) and -[subprocess contract](../integrations/subprocess.md) describe the starting point, -not requirements to reproduce during migration. - -## Details for the feature roadmap - -The product and interface direction is settled. The following details need -concrete implementation choices in the roadmap, but do not require another -architectural discussion before drafting it. - -### Outcomes and process lifecycle - -Map PromptKit's typed errors and reported outcomes into CommandKit conventions, -preserving its distinction between a completed content check reporting -`ValidationFailed` and an operational error. Select any necessary domain exit -code without reusing the current validation-failure exit 2, which conflicts with -CommandKit's usage convention. Also specify artifact/report delivery failures -using CommandKit's presentation-failure behavior where applicable. These are -adapter mappings, not a new application validation policy. - -Signal cancellation and the whole-operation deadline remain application -responsibilities. Specify their mapping to the CommandKit invocation context -and PromptKit operation timeout, including the application deadline flag and -units, separately from the standard per-attempt timeout flag. - -### File delivery - -The roadmap and implementation plan specify ordinary report-file handling and -delivery ordering relative to stdout. The caller owns redirected destinations; -Scriptorium does not infer them or check for collisions with the report path. -Partial delivery follows native outcomes and the agreed result-availability -boundary. - -### Adoption and verification - -Confirm the released dependency combination, complete the application-specific -flag and loader mappings, and sequence replacement and removal of CLI code. -Define appropriate verification for the selected behavior and update canonical -documentation, examples, and release migration guidance as implementation lands. - -## Roadmap handoff - -The [adoption roadmap](commandkit-adoption.md) incorporates these decisions and -integration details. Keep implementation status there; retain this notepad as -the discussion record. - -[upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md -[upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md new file mode 100644 index 0000000..fbc309b --- /dev/null +++ b/docs/roadmap/future.md @@ -0,0 +1,27 @@ +# Future Work + +The completed CommandKit adoption, implementation plan, Narratio request, and +earlier adoption/policy roadmaps remain available in +[Git history](https://forge.maximumdirect.net/eric/scriptorium/src/commit/f5573f7c8f2ddf0d69414a05c978c8d6cfe291e7/docs/roadmap). +Current behavior belongs to the [CLI](../cli.md), [configuration](../config.md), +[HTTP API](../api.md), and other canonical contracts. + +## Deferred Directions + +- **HTTP design review:** separate work before v1.0; CommandKit adoption retained + the existing HTTP interface and execution-report representation. +- **Embedded framework configuration:** deferred pending upstream support for a + native handoff preserving resource context and inspection evidence. The current + application settings select a separate PromptKit entry file. +- **Dynamic resource completion:** possible enhancement beyond native command, + flag, static-value, and path completion. +- **Configurable namespace defaults and automatic report collection:** possible + enhancements if concrete operator needs arise. Current callers select explicit + namespaces and report paths and own retention. +- **Selected-format accessor:** optional upstream CommandKit capability; not a + prerequisite for the completed stdout-based generation/report interface. + +These directions do not select additional APIs, command syntax, implementation +order, or delivery dates. Independently versioned report envelopes and +programmatic invocation-failure categories remain potential upstream discussions +if a concrete consumer need emerges, not missing migration requirements. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md deleted file mode 100644 index b4f6952..0000000 --- a/docs/roadmap/implementation.md +++ /dev/null @@ -1,816 +0,0 @@ -# CommandKit Adoption Implementation Plan - -## Purpose And Execution - -Implement the target in the [CommandKit adoption roadmap](commandkit-adoption.md). -This plan owns the implementation steps and concrete adapter choices; the roadmap -owns product intent and target behavior. The [migration notepad](commandkit-notepad.md) -records the discussion. [ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md), -[ADR 0005](../adr/0005-configkit-boundary.md), and -[ADR 0004](../adr/0004-definition-boundary.md) remain authoritative. - -Audience: a Luna coding agent implementing one numbered stage per prompt, in -order, as one end-to-end sprint. Intermediate stages may leave compilation or -tests temporarily broken. Do not build compatibility dispatch, parallel CLI -surfaces, feature toggles, or temporary abstractions to make intermediate stages -shippable. The final assembled application is the completion boundary. Add the -stage's relevant tests with its implementation; run focused checks when runnable -and record deferred checks for Stage 9. Follow the agent policy for focused -commits, accurately identifying incomplete validation. - -Start with [development guidance](../development.md). Read the applicable -[agent](../policy/agents.md), [architecture](../policy/architecture.md), -[testing](../policy/testing.md), [documentation](../policy/documentation.md), and -[OSS](../policy/oss.md) policies. Use the [release policy](../policy/release.md) -for release-related documentation and build metadata. Preserve unrelated work. -This plan does not authorize release publication, upstream repository changes, -or rewriting accepted ADR decisions. - -Planning baseline: `bcb1a76e345ef7f3720dcbce7c446beb0d9db23b`. -The current application uses Go 1.27.0, ConfigKit v1.2.1, and PromptKit v0.23.3, -with validation/build toolchain Go 1.27.4. Relevant starting components are -`cmd/scriptorium`, `internal/adapter/cli`, `internal/config`, `internal/format`, -`internal/report`, and the unchanged `internal/adapter/http`. - -## Released Dependencies And Selected Integration - -The reviewed public APIs are documented at CommandKit revision -`d330d7637f2e7507eca931a899397222c82bc892` in its -[consumer guide][upstream-guide] and [CLI contract][upstream-cli]. The released -baseline is: - -| Module | Reviewed release | Release source commit | -| --- | --- | --- | -| `go.maximumdirect.net/commandkit` | v0.7.0 | `b57bfe176cff05a892e6cb07ebb5f350239e55d4` | -| `go.maximumdirect.net/ckconfig` | v0.9.0 | `9962368f0c1ea1f6ad010638e94621091105d745` | -| `go.maximumdirect.net/ckprompt` | v0.10.0 | `c9a56e1b15f2169881a91fca4e1f4a1c475e057a` | - -Use the reviewed released combination and verify it in Stage 1. Preserve -ConfigKit v1.2.1 and PromptKit v0.23.3; ckprompt's PromptKit v0.23.2 minimum is -not a reason to downgrade. Raise any demonstrated compatibility problem before -expanding this sprint into another framework upgrade. - -No selected-format accessor is required. Main results go through the native -invocation reporter to stdout, with caller-controlled redirection. The separate -`--report` file uses the existing `RenderReport(writer, report, format)` API, -with the format unset unless `--report-format` is supplied. -The upstream accessor proposal is optional and does not block any stage. Do not -add a second reporting-flag parser or private-API workaround. - -## Settled Application Choices - -### Command And Selection Mapping - -Install the native `config` and `promptkit` families, plus application commands -`run PROMPT_ID` and `serve`. Use `ckprompt.Declarations` to install native -convenience aliases. Install equivalent command-scoped aliases for applicable -reused bindings on `run`; do not add legacy command aliases or a duplicate prompt -flag. Native help, version, completion, format, verbosity, and outcomes replace -their old counterparts without a compatibility parser. - -| Input | Application mapping | -| --- | --- | -| `--config` | Application main-source selection on every configuration-consuming command, including the `promptkit` scope and family. Preserve explicit presence, including an empty value. | -| `--overlay` | Pass the supplied value to ConfigKit's `Options.Overlay`. At v1.2.1 this is a name, not a filesystem path: native empty/default selection and `overlays/NAME.yml` lookup apply. Do not add a second overlay interpreter or a fallback root. | -| `--promptkit-source`, `--schema-dir` | Removed from every command; framework entry-file and schema-root settings come from application configuration. | -| `--addr`, `--artifact-root`, `--max-request-bytes`, `--max-artifact-bytes`, `--max-response-bytes` | Presence-aware application `server` overrides on `serve` only. | -| `config ... --set POINTER=JSON` | Native override records for `app`, passed directly to ConfigKit with native conflict handling. Enable the feature only on `app`. | -| Native `config diff --against-config`, `--against-overlay`, `--against-set` | Independent right-side selections and supported native overrides. No application-defined `--against-*` flags. | -| `--run-timeout DURATION` on `run` | `time.ParseDuration`, then unchanged into `RunRequest.OperationTimeout`. Positive values add the native operation budget; zero and negative values add none under PromptKit v0.23.3. No second application timer or positivity restriction. | -| Native `--llm-timeout-seconds` / `--timeout-seconds` | Integer per-attempt timeout through the ckprompt execution binding; no old duration conversion. | - -Install no application-defined flags or commands under `config`, including -source/schema flags, HTTP flags, or their `AgainstName` counterparts. Application -configuration inspection can use native `--set`; framework inspection obtains its -application settings through native `--config` and `--overlay` selection. -`run` accepts native configuration selection, request controls, and delivery -controls; `serve` retains HTTP controls and excludes generation request controls. -Do not add source/schema convenience flags. The configured `transient_retries` -remains an engine default; the native execution flag overrides a request. - -ConfigKit remains responsible for loading and all precedence, resolution, and -inspection semantics. Native `--set` records can address nonconflicting paths; -duplicate and ancestor/descendant-overlapping records are rejected by ConfigKit. -Record order does not grant precedence. -Preserve native diagnostics without local conflict filtering, deduplication, or -merging. This also applies independently to each comparison side, including -`--against-set`. Keep cwd-relative application path values and source-relative -PromptKit resources. Replace the legacy discovery paths with ConfigKit's native -directory presets and filename conventions in this order: `WorkingDirectory`, -`UserConfigDirectory`, `HomeDirectory`, `UnixSystemDirectories`. Retain each -preset's native filename rules, optional exhaustion, and terminal selected-file -errors. One main file is selected; the discovered candidates are not layers. - -### Framework Configuration Settings - -Use the following application settings shape: - -```yaml -promptkit: - configuration: ./promptkit/collections.yml - schema_dir: ./schemas -``` - -`promptkit.configuration` selects one external framework file. An omitted or -empty value supplies no external main, preserving defaults-only engine loading. -`promptkit.schema_dir` retains the existing schema-root default and semantics. -Application path values remain cwd-relative; imports and resource references -within the framework document retain their native source contexts. The existing -`transient_retries` setting continues to supply the engine retry default. - -Replace `promptkit_sources` and top-level `schema_dir`; do not retain aliases or -a compatibility conversion. Load the external file as an import-enabled -`configkit.Input` in `promptkit.ConfigurationSources.Main`. Its glob imports -discover collection entry files; no application-managed source list or directory -classification is needed. PromptKit retains its bundled configuration underlay. - -The `promptkit` application section is acquisition settings, not an embedded -PromptKit definition document. Embedding profiles, prompts, backends, or -collections there is deferred until upstream supports a native handoff with the -required resource context and inspection evidence. Do not emulate it by -extracting and reloading application values; no upstream change is required for -this migration. - -### Outcomes And Delivery - -| Condition | Outcome | -| --- | --- | -| Completed run without `ValidationFailed` | Native success, status 0, subject to delivery. | -| Completed run with `ValidationFailed` | `commandkit.Domain("validation_failed", 4)` with a useful explanation; deliver the returned artifact and native result. | -| Syntax or declaration-input errors, including an explicitly empty report path | Native usage, status 2. | -| Configuration load errors | Use `ckconfig.ClassifyConfigurationError` and native diagnostic evidence: usage 2 for classified invalid configuration, otherwise operational 1. | -| Lookup, preparation, generation, capacity, operation-timeout, cancellation, or other operational errors | Operational 1 with safe explanation and preserved typed cause. Request failures are not completed content-validation failures. | -| Native `config diff --check` differences | Native status 3, unchanged. | -| Result or diagnostic presentation failure | Preserve CommandKit's finalization rules: success/usage become operational 1; a nonzero domain status remains nonzero and retains its classification. | -| Report file delivery failure | Operational 1 for an otherwise successful run. Preserve an already nonzero domain status 4 while adding the delivery explanation/cause. | - -Use `errors.Is`/`errors.As`, not error-text matching. Apply cancellation and -typed operation-timeout handling before configuration classification. Do not -classify every `ErrInvalidConfig` wrapper as invalid user input without native -evidence. Retain safe explanations for provider failures; causes are inspectable -Go errors, not permission to print credential-bearing provider payloads. - -Use a main `commandkit.Report` with the actual `*promptkit.RunResult` as `Value`. -Its reusable text template emits `Artifact.Body` as bytes represented as a string, -with no added newline, header, escaping, or summary. Native JSON/YAML serialization -remains upstream-owned, including byte representation and native metadata. - -Submit the main report through `Invocation.Reporter().Report`. There is no -`--output` or legacy `--out` flag. Callers save stdout using shell redirection or -their subprocess API; Scriptorium keeps diagnostics on stderr. Native quiet -suppresses the main result even when stdout is redirected. Consumers wanting -that result omit `--quiet`. - -`--report PATH` additionally renders `commandkit.Report{Value: result}` through -`commandkit.RenderReport`, without the main report's artifact-only text template. -Optional `--report-format text|yaml|json` selects its native format independently -of stdout's `--format`. When omitted, pass the zero `commandkit.Format` value -(`""`) for native automatic rendering. Do not substitute JSON, YAML, or text. -CommandKit currently renders structured values as YAML in automatic and text -modes; future upstream defaults flow through without application policy changes. -Filename extensions do not select the format. - -This application-owned file write still occurs in quiet mode. Omitting `--report` -creates no separate report. Use ordinary create/truncate operations (mode 0644 -for newly created files, subject to umask), preserve normal OS behavior for -existing files, and handle render/write/close errors. Do not create parent -directories. An explicit empty report path is a usage error; `-` is an ordinary -filename. The caller owns redirected destinations, including keeping the main -output file separate from the report. Do not add stdout-destination discovery -or collision checks in Scriptorium. - -Once a result is available, attempt main delivery first, then the separate -report, even if the first attempt fails. Open the report only after a result -exists; a resultless failure leaves an existing report untouched. This does not -govern a caller's redirection: a shell may create or truncate its destination -before Scriptorium runs. Delivery is nontransactional; written bytes remain -after failure. No rollback, atomic replacement, symlink sandbox, or additional -filesystem hardening is requested. - -## Stage 1: Select Released Dependencies And Establish Command Composition - -**Status: Complete.** Selected CommandKit v0.7.0 -(`b57bfe176cff05a892e6cb07ebb5f350239e55d4`), ckconfig v0.9.0 -(`9962368f0c1ea1f6ad010638e94621091105d745`), and ckprompt v0.10.0 -(`c9a56e1b15f2169881a91fca4e1f4a1c475e057a`); retained ConfigKit v1.2.1, -PromptKit v0.23.3, Go minimum 1.27.0, and validation toolchain 1.27.4. -Native composition now owns dispatch and finalization; application acquisition -and command effects remain explicit unfinished callbacks for subsequent work. -Verified configuration-free help/version/scope discovery and Bash/Zsh/Fish -completion, all-package test compilation, tidy module metadata, linked dependency -selection (including Windows-only mousetrap), and release notice paths. -Full behavioral checks remain deferred to Stage 9: the old CLI integration tests -still describe the retired interface, and the new application handlers are not -yet implemented. No compatibility dispatch was retained. - -**Primary files:** `go.mod`, `go.sum`, `internal/adapter/cli` composition, -`docs/oss/attribution.md`, and applicable `docs/oss/licenses/` texts. - -1. Verify the reviewed released module combination above. Record the actual - versions and complete source commits in this plan's implementation status - and attribution entries as appropriate; use released modules, not sibling - checkouts, workspaces, vendoring, or replacements. -2. Add CommandKit, ckconfig, and ckprompt dependencies. Keep the existing Go - minimum and validation toolchain unless the selected dependencies supply a - concrete contrary requirement; raise such an expansion rather than guessing. - Verify selected PromptKit/ConfigKit versions and tidy the module metadata. -3. Create the CLI composition entry point in `internal/adapter/cli`. Accept a - context, application identity, argv, and output streams; let `App.Execute` - own parsing and finalization and return its outcome/status to the entrypoint. - Keep package/file choices straightforward rather than introducing a new - framework or interface for each factory. -4. Establish declarations for `run`, `serve`, the native configuration suite, - native PromptKit suite, and `commandkit.Completion("scriptorium")`. Fill the - application loaders and handlers in later stages. Native root/group/help - behavior replaces the dispatch switch. Declaration construction, help, - version, scope discovery, and static completion must not load application - or framework configuration or invoke providers. -5. Apply the OSS House Format to CommandKit, ckconfig, and ckprompt using their - actual release commits and module-subdirectory notice paths. Inspect linked - dependencies, including Cobra, pflag, and any applicable mousetrap use, - rather than treating every module-graph tool as a runtime dependency. - Reuse existing verbatim license texts and add missing applicable ones. - Preserve current project licensing and notice navigation. - -**Evidence:** selected module metadata has no replacements or unintended -PromptKit downgrade; declaration construction is valid when wired; help/version -can be exercised without a readable application configuration. Check notice -paths against the selected commits. Final composed behavior is checked in Stage 9. - -## Stage 2: Adapt Authoritative Application Loading And Shared Selectors - -**Status: Complete.** Application loading uses the selected native directory -presets, strict nested `promptkit` acquisition settings, and ConfigKit's native -override/conflict handling. The shared engine uses one optional import-enabled -main file and retains the bundled underlay. Removed the render default, -source/schema bindings, source classification, and parser-owned application -override collector. HTTP bindings retain explicit presence and `int64` limits. - -Verified on Go 1.27.4: configuration package tests and race checks, plus focused -native composition/loading/engine tests and race checks using the new source -files directly. Coverage includes discovery order and filenames, optional search -exhaustion isolated from host system configuration, explicit-empty selections, -imports/overlays, duplicate and overlapping override evidence, normalization, -HTTP empty/zero/full-width values, fresh loads, cancellation, removed flags, and -collection-relative message resources. Full-package compilation is intentionally -deferred: the unreachable old CLI files/tests still reference retired settings -and helpers and will be removed/replaced in Stage 8. Do not interpret the focused -checks as an assembled-application validation; finish that in Stage 9. - -**Discovery and source decisions: Settled.** Implement the ordered native search -and single external framework entry file specified above. Remove source/schema -CLI flags and the general source-list interface. Embedded framework definitions -remain deferred; they are not an upstream prerequisite for this stage. - -**Primary files:** `internal/config/{load,document,settings}.go`, their tests, -and CLI application-loading/engine-construction helpers. - -1. Retain one `configkit.Load` boundary returning its actual - `*configkit.Result[Document]`. Adapt selection into `LoadOptions` or its - replacement: explicit config presence chooses `File`; omission chooses - `SearchConfig` with the agreed native directory presets and their filename - defaults. Replace the two literal legacy paths instead of preserving their - precedence or limiting filenames to `config.yml`. Keep native optional-search - exhaustion and selected-file error behavior. Imports remain enabled; overlay - and override records go directly into ConfigKit. Preserve wrapped error identity. - Respect the invocation context at the application boundary without claiming - ConfigKit's synchronous work can be forcibly interrupted. -2. Replace `flag.FlagSet.Visit` and parser-owned override collection with typed - CommandKit bindings retaining `Supplied.Set`. Convert only supplied - HTTP flags on `serve` into correctly labeled ConfigKit overrides. Configuration - commands pass only native `Selection.Overrides`; they have no named application - overrides. Let ConfigKit validate records and report conflicts. Do not load - framework definitions during application inspection. Remove source/schema - flag bindings, source-list override construction, and file/directory - classification used by those flags. - Preserve the existing nonnegative `int64` domain for HTTP byte limits, - including zero as unlimited; do not narrow it to a platform `int` or add a cap. -3. Keep schema, defaults, normalization, and domain validation inside the - existing ConfigKit definition callbacks. Record normalization through native - `configkit.Normalize`/resolution evidence. `Settings` remains a conversion - of completed values, not another resolver or merger. -4. Remove `Document.Defaults`, `DefaultsDocument`, `defaults.render_format`, - `AppSettings.DefaultRenderFormat`, associated normalization/validation, and - the resulting `internal/config` dependency on `internal/format`. Replace the - source-selector list and top-level schema root with the typed `promptkit` - settings above; move their applicable defaults, normalization, validation, - and evidence paths into the new schema. Strict ConfigKit decoding handles - retired fields; add no compatibility mapping. -5. Build the shared engine from completed application settings. When configured, - construct `configkit.File` from the resolved `promptkit.configuration` and - pass it in an import-enabled native main input; otherwise leave `Sources.Main` - nil. Supply the configured schema - root and existing retry default, retaining PromptKit's bundled underlay. - Remove application use of `DirectoryInputs` and one-underlay-per-source - construction. The framework entry file imports both collection-entry globs; - each collection supplies its namespace and relative imports. Keep native - acquisition, composition, validation, and inspection evidence intact. -6. Use fresh application input per comparison side and invocation-owned state - under the native factory lifecycle; comparison may share that state without - sharing either side's selected values. Start without an engine/config cache: - separately reached loads are ordinary - loads, not an immutable-snapshot contract. Server engine lifetime is handled - separately in Stage 7. Small invocation state for acquisition diagnostics is - acceptable and must not alter effective configuration. - -**Evidence:** real ConfigKit-backed tests cover omitted versus explicit-empty -config/overlay selection, the selected native discovery presets and filename -conventions, supplied zero or empty HTTP overrides on `serve`, native `--set` -records, nonconflicting combinations, and native duplicate and -ancestor/descendant conflict rejection with diagnostic evidence. Also cover -the new settings shape, optional versus selected framework file loading, -imported collection resources and their source contexts, normalized values and -their evidence, and removal of retired fields and flags. Adapt existing search -tests to the selected presets; reuse import/source coverage without reproducing -ConfigKit's exhaustive discovery or -composition matrix. - -## Stage 3: Install Native Configuration Scopes And Independent Comparison - -**Status: Complete.** Installed native `app` and `promptkit` scopes with all five -operations, path/metadata capabilities, and native-only selectors. Only `app` -accepts temporary overrides. The PromptKit acquisition decorator carries -application diagnostics separately and restores typed application failures before -classification; it does not place application evidence in the framework view, -rewrite effective values, or cache configuration/engines. - -Verified on Go 1.27.4 with focused real-library integration tests, race checks, -and vet: application-only inspection with unavailable framework sources, -normalized show/explain agreement, root/index/escaped-key paths, redaction, -independent explicit and implicit comparison selections, independent overlays and -native overrides, diff-check status 3, disabled framework/all-scope overrides, -absent custom configuration flags, and diagnostic/cause preservation for both -comparison sides. Full-package checks remain deferred while the unreachable -legacy CLI files/tests await Stage 8 removal. - -**Primary files:** CLI configuration-suite composition and loaders; replace -`internal/adapter/cli/config.go` and `framework_config.go` responsibilities. - -1. Construct `ckconfig.Command(ckconfig.Suite[...])` with `app` from - `ckconfig.FromConfigKit` and `promptkit` from `ckprompt.ConfigScope`. - Enable native validate/show/sources/explain/diff and supported path/metadata - modes. Keep native scope discovery and default scope selection. -2. Mark only the application scope as supporting temporary overrides, passing - those records through Stage 2. Retain the PromptKit scope's native disabled - override feature, including native capability checks for all-scope requests. -3. Install no application selectors or `AgainstName` bindings. Use native - configuration/overlay/override selection and fresh per-side input where needed. - Each comparison loader must consume that side's `Selection` and input; - do not cache the first engine into the second side. Delegate comparisons - to the returned native adapters instead of assembling a synthetic document. -4. Preserve native view metadata, findings, sources, path discovery, explanation, - redaction, diff reports, and failure classification. No local source DTO, - JSON Pointer interpretation, custom effective document, explanation-tree - reconciliation, or replacement formatter is needed. -5. Route application-load diagnostics for framework acquisitions through - `ckconfig.AdaptDiagnostics` and `commandkit.Acquired` diagnostics/explanations, - retaining the adapter's existing framework evidence. Small callback - decoration may attach application acquisition messages; do not insert app - findings into the PromptKit configuration view or merge their evidence trees. - Retain diagnostics from each reached comparison side and label their context. - Application-scope acquisition itself stays with `FromConfigKit`. - -**Evidence:** app inspection works even with unreadable framework sources; -framework inspection uses sources selected by `--config`/`--overlay`; native -show and explain agree with the resolved callback values. Exercise native -root/index/escaped-key paths and redaction through representative integration -cases, independent left/right configs/overlays/native overrides, and diff-check -status 3. Verify custom configuration flags and comparison counterparts are absent. -Verify app overrides are available and framework overrides are not emulated. - -## Stage 4: Install Native PromptKit Resources, Requirements, And Preview - -**Status: Complete.** Composed all twelve native callbacks, empty-default -namespace views, and native convenience declarations. Request builders remain -nil so native seeds pass through unchanged. Every callback carries application -acquisition evidence separately, preserving framework reports and typed errors. - -Verified on Go 1.27.4 with focused real-library tests, race checks, and vet: -exact required and undeclared input names, optional/conditional dependencies, -explicit-empty variable presence, complete versus partial reports and structured -issue codes, qualified prompt/profile identities, namespace selection, selection -failures, and discovery without artifacts, schemas, or generation credentials. -Also checked five inventories and native default/filter behavior, three named -inspections, content-bearing prepared reports in automatic/text/YAML/JSON modes, -and concrete validation/preparation without generation. A loopback-only provider -verified explicit smoke execution and native unsuccessful findings with status -zero, without disclosing provider payloads. Narratio's shared-context discovery, -validation, and preview coverage is present; execution consistency is checked -with positional generation in Stage 5 and the assembled workflow in Stage 9. -Legacy-file compilation cleanup remains deferred to Stage 8. - -**Primary files:** CLI PromptKit-suite composition, engine-loading adapters, -and behavior tests replacing custom definition/prepared inspection tests. - -1. Compose `ckprompt.FromEngine`, `WithRequestValidation`, - `WithRequestPreparation`, and `WithSmokeTesting`, using the common application - selection and engine loading from Stage 2. Enable all twelve callbacks: - five inventories, three named resource inspections, requirements discovery, - concrete validation, preparation, and smoke testing. -2. Enable `ckprompt.WithNamespaces` with empty application defaults and install - `ckprompt.Declarations`. Let the adapters apply their native engine views; - the common engine loader returns an unscoped engine. Retain inventory filters - and default listing behavior rather than forcing all namespaces. -3. Request builders should be nil where the seed already is the desired - request. If application mapping needs a builder, start with the supplied - seed and preserve its fields, explicit values, and namespace context; do not - reread bindings or merge a different request after the builder returns. - The configured retry default belongs in the engine, not a second request pass. -4. Carry application acquisition diagnostics through the native callback return - channels as in Stage 3, preserving framework messages and typed failures. - Let CommandKit control presentation and verbosity; do not write directly to - stderr from loaders or suppress native reports based on local interpretations. -5. Expose native prompt messages, profile/backend inspection, and prepared-run - reports as returned, including their content-bearing nature. No old summary - projection or local schema-version envelope. Preview remains native - `promptkit show prepared PROMPT_ID`, with native text/YAML/JSON behavior and - stdout capture for file saving. -6. Keep discovery distinct from preparation: requirements discovery does not - need generated input artifacts, model credentials, schemas, provider calls, - or a generation output path. Loading configuration and captured message - resources is still expected. Concrete validation/preview keep their upstream - preparation-time prerequisites. Do not reject partial discovery or convert - unsuccessful/unsupported smoke findings into extra application failures. - -**Evidence:** implement the nine linked -[Narratio scenarios](narratio-feature-request.md#consumer-acceptance-scenarios) -with a small set of real-library fixtures covering exact required names, -undeclared references, optional/conditional inputs, variable presence including -empty values, complete versus partial reports, profile/prompt identity, and -selection failures. Check native inventories/namespace filters, one named report -per resource kind, and preparation/validation without generation. Smoke-test -wiring uses a controlled local provider or injected public LLM client, never real -credentials or paid calls. Reuse fixture coverage rather than duplicating the -upstream analysis or rendering suite. - -## Stage 5: Implement Positional Generation, Request Mapping, And Outcomes - -**Status: Complete.** `run PROMPT_ID` uses native resource/input/execution -bindings and equivalent command-scoped aliases, typed namespace strings and -public engine views, and one `Engine.Run` dispatch with the invocation context. -Operation durations pass through unchanged. Main results use the native reporter -with the artifact-only byte-preserving text template; structured modes retain -the native result. Completed content-validation failure is domain status 4; -resultless operational failures remain status 1 with preserved typed causes and -safe explanations. Configuration classification uses native diagnostic evidence. - -Verified on Go 1.27.4 with focused controlled-provider integration tests, race -checks, and vet: canonical/preferred aliases, input file/literal precedence, -commas and additional equals signs, explicit numeric zero and empty reasoning, -service tier and extra parameters, independent namespaces and exact qualified -IDs, session context, raw stdout, native JSON/YAML results, verbose diagnostic -stream separation, invalid-content delivery/status 4, and operational failures -without a result or provider-payload disclosure. Typed-error/nil-result checks -and the shared Narratio discovery/preparation/generation fixture cover mapping -and context consistency. Actual timeout/cancellation lifecycle checks follow in -Stage 7; full-package compilation still awaits Stage 8 legacy removal. - -**Primary files:** the new application `run` declaration, request/outcome -helpers in `internal/adapter/cli`, and run integration tests. - -1. Declare exactly one required positional `PROMPT_ID` with CommandKit, using - shared native config/overlay selection. Reuse - `ckprompt.NewResourceFlags` for profile and session selection, - `NewPromptInputFlags` for variables/text/files, and `NewExecutionFlags` for - all native execution controls. Do not install the reusable prompt flag: - the operand supplies that ID. The native run request has no direct backend-ID - override, so do not invent a backend flag or synthetic profile for `run`. -2. Map the bound values directly into a native `RunRequest` (profile, session, - inputs, vars, execution, retry count). Preserve pointers and explicit values - rather than implementing local inheritance/clearing rules. Keep native - assignment semantics: first `=` separates a mapping, commas are literal, - and the last text/file occurrence for an input wins. -3. Install the native short convenience spellings on `run` with - `commandkit.FlagAliasFor`, matching the reused binding meanings. Cover - profile/session, var, input-text/input-file, all execution controls, and - `--input`/`--llm-input` as literal-text aliases. Do not retain `--out`, - `--execution-report`, `--llm-base-url`, old `--timeout`, `--prompt-id`, or - `--profile-id` merely for compatibility. -4. For `run`, declare the three standard namespace flags and convenience aliases - through ordinary typed CommandKit string flags. The reviewed reusable - resource bindings do not export namespace bindings; use public - `Engine.WithNamespaces(promptkit.Namespaces{...})`, which is the supported - application-engine-view integration. Leave validation of namespace values - and ID selection to PromptKit. No local qualification or rewriting of stored - references, and no configurable default namespace. -5. Pass the invocation context to `Engine.Run` and map `--run-timeout` unchanged - to `OperationTimeout`. Keep generation single-dispatch at the adapter level; - retries, repairs, backend admission, credentials, and preparation belong - upstream. Do not call `ValidateRequest` first as a new execution prerequisite. -6. Implement the outcome table above. A completed invalid result is still - delivered and returns domain status 4. A resultless operational error has - no synthesized result or alternative report shape. Treat an unexpected nil - result without an error as an operational integration failure, not success. - Preserve typed causes and safe terminal explanations. -7. Build the native result report/text template and submit stdout results - through the invocation reporter. Keep any retained generation summary as a - native Info message, normally hidden at ordinary verbosity. Stage 6 adds - the separate native report without changing the result shape. - -**Evidence:** real-engine/controlled-provider tests exercise the assembled -positional command, preferred aliases, literal/file precedence, comma-containing -values, numeric zero and reasoning empty values, service tier/extra parameters, -qualified IDs and independent namespaces, raw byte output, native structured -serialization, completed invalid content/status 4, and resultless operational -failure/status 1. Include a small typed-error mapping table rather than parsing -error prose. Use native config classification for representative load failures. -Verify `--verbose` leaves artifact stdout unchanged and routes emitted Info and -Warning messages to stderr under native visibility rules, without fixing their -wording or requiring a particular generation summary. - -## Stage 6: Add Separate Native Report Delivery - -**Status: Complete.** Added presence-aware report paths, typed native report -formats with no default, and native completion hints. Validation precedes model -execution and file creation. Main delivery still uses the invocation reporter; -the separate file renders the same native result without its artifact-only -template, independently of quiet and stdout format. Ordinary create/truncate -writes handle render/write/close errors without making parents. CLI observation -collection and its old report-file writer have been removed; HTTP is unchanged. - -Verified on Go 1.27.4 with focused integration tests, race checks, and vet: -automatic/explicit native report formats, extension independence, replacement, -literal `-` filenames, quiet and redirected subprocess stdout, preflight errors -before provider/file effects, unchanged existing reports on resultless failure, -stdout failure followed by a report attempt, report failure after main success, -native render failures, retained presentation/file errors, and domain status 4 -surviving delivery failure. Subprocess checks invoke the native adapter in a test -executable; final shipped-binary verification follows the legacy-file cleanup. -Full-package compilation remains deferred to Stages 8–9 as previously recorded. - -**Primary files:** CLI generation-delivery helpers and focused delivery tests. - -1. Add `--report` as a presence-aware application file flag with path completion. - Add optional `--report-format` with typed binding and completion for the native - `text`, `yaml`, and `json` formats; leave its default unset. Reject an explicitly - empty path or invalid format as usage errors before executing the model. Do - not create files during validation or add a main-output destination flag. -2. Main stdout uses Stage 5's report through `Invocation.Reporter().Report`. - Render the separate report through `RenderReport` with - `commandkit.Report{Value: result}`, sharing the native result but no text - template. Pass the empty format when `--report-format` is omitted; - otherwise pass the explicitly selected native format. The invocation reporter - owns main format selection, including automatic artifact-template output. - No selected-format accessor is needed. Extensions never select formats. -3. Keep the report file effect independent of console quiet selection. Do not - temporarily change reporting mode, rerun `App.Execute`, capture stdout and - parse it back, or replace native structured serialization to obtain the report. - Keep file rendering outside reporter render callbacks to avoid reentrancy. -4. Attempt main delivery and then the requested report even when the first - fails, retaining every relevant delivery error. Include useful failure - explanations and preserve the selected nonzero domain outcome. Console - presentation failures remain recorded by CommandKit finalization; report - file errors need their own outcome handling because they bypass its reporter. -5. Remove the CLI observer/report collector wiring and old report-file format. - Leave `internal/report` and HTTP report attachment intact. Only a returned - native run result is eligible for the new CLI report file. - -**Evidence:** cover default/text raw bytes and JSON/YAML through stdout, including -a subprocess whose stdout is redirected to a file. Compare omitted and explicit -report formats against native `RenderReport` of the same value without a template; -use an empty format for the omission expectation, not hard-coded YAML. Confirm -the separate report retains the full result and metadata, independently of the -main format and filename extension. Quiet suppresses main output, including -redirected stdout, while an explicitly requested report is still written. Test -empty report paths and invalid formats before model execution, replacement -without parent creation, stdout failure followed by report attempt, report failure -after successful main delivery, and an unchanged existing report on a resultless -operational failure. Use temporary files and a small failing-writer seam for -stdout/render failures. Confirm status 4 survives a delivery failure while its -explanation identifies the failure. No exhaustive filesystem matrix. - -## Stage 7: Wire Process Metadata, Cancellation, And Server Startup - -**Status: Complete.** Entrypoint execution now uses an interrupt/SIGTERM context, -cleans signal registration before process exit, and returns the native finalized -status. Version/revision string variables support linker metadata; local and -hosted release builds supply the selected version and full source commit without -changing targets, toolchain, publication guards, or release-completion semantics. -`serve` loads resolved settings once, constructs one restricted reader and shared -engine, retains the HTTP handler/limits/header timeout, and closes listener and -active connections on cancellation. Startup uses native Info reporting; canceled -and unrelated server failures retain operational outcomes and typed causes. - -Verified on Go 1.27.4: focused native-adapter tests/race checks and vet, existing -HTTP race regressions (including reader/report/capacity behavior), release-script -tests, and local/hosted shell syntax checks. Explicit readiness coordination -covers server startup, a file-backed HTTP run with its execution report, and -shutdown during active engine work. Timeout checks distinguish native operation -budgets, earlier parent cancellation/deadline, zero/negative budgets, and a -per-attempt timeout. Framework load failures retain their native diagnostics. -Entrypoint package tests and the linked version/revision binary check are -deferred until the legacy files are removed; include them in Stage 9's full -application verification. No release was published. - -**Primary files:** `cmd/scriptorium/main.go`, CLI `serve` declaration, -`scripts/release.sh`, `.woodpecker/release.yml`, and lifecycle tests. - -1. Build the CLI identity as `scriptorium`, with caller-supplied version and - revision. Add entrypoint string variables defaulting to `dev` and empty - revision for ordinary builds, suitable for `-X main.version=...` and - `-X main.revision=...`. Supply the release version/source commit in the - existing release script and hosted build flags. Keep Go 1.27.4, build targets, - publication guards, and release-completion semantics unchanged. -2. At the process entrypoint, create a signal-aware context for interrupt and - SIGTERM, pass it into execution, clean it up before `os.Exit`, and return - CommandKit's finalized status without translating it to the old CLI constants. - Keep this separately testable without signaling the test runner itself. -3. Implement `serve` as an application command consuming Stage 2's resolved - server settings. Construct the existing restricted artifact reader and inject - it into one PromptKit engine shared by that server's requests. Install the - existing HTTP handler and limits; retain `ReadHeaderTimeout` and engine retry - defaults. Do not construct engines per request or remove backend capacity - coordination. -4. Send startup information through native Info reporting and failures through - native explanations/causes. Do not add raw stdout server banners. Integrate - context cancellation with `http.Server.Close` so the listener and active - connections are closed; treat the resulting `ErrServerClosed` as expected - cancellation with a useful nonzero operational outcome. Retain operational - failure for unrelated listen/serve errors. This adds no graceful-drain deadline - or guarantee that context-ignoring work has finished. -5. Leave HTTP routes, DTOs, status mappings, optional execution reports, - restricted-reader policy, and concurrency contracts unchanged. Continue using - the HTTP observer collector; native CLI result reporting does not replace it. - -**Evidence:** test injected context cancellation reaching a real engine operation -without a duplicate timer; distinguish native operation timeout from earlier -parent cancellation. Include zero/negative operation budgets and independent -per-attempt timeout mapping. Exercise actual `serve` startup with a loopback -listener, representative HTTP request, and controlled shutdown using explicit -readiness coordination. Reuse the HTTP reader/DTO/report/shared-capacity suite -rather than duplicating it. Build a binary with test identity flags and check native -version output. Test-local fallback deadlines prevent regressions from hanging. - -## Stage 8: Retire Superseded Machinery And Update Canonical Documentation - -**Status: Complete.** Removed legacy parsing/dispatch, custom inspection/source -DTOs and writers, retired CLI tests, and the unused formatter package. Retained -architecture boundaries, native integration protection, checkout-discovery -coverage, and the unchanged HTTP/report implementation and regression suites. -Maintained examples now select external framework entries with native imports; -both collection-entry spellings and multi-definition discovery remain present. -Canonical CLI/configuration/process/operations/internal/development/policy owners -and navigation reflect the cutover, with a focused CLI migration guide distinct -from the earlier framework-format guide. Accepted ADRs and release-note history -are unchanged; deferred HTTP redesign and dynamic completion remain deferred. - -Verified on Go 1.27.4: full tests and race suite, vet, ordinary build, module -tidiness, formatting/diff checks, all maintained application configs in both -native scopes, application overlays, maintained preview scripts, a structured -schema preview, and local Markdown links/anchors (42 files). Added maintained -example loading/preparation protection and adapted fresh-checkout discovery to -native preview. Entrypoint package tests now run and pass. Linked identity, -release-target builds, and the final assembled acceptance audit remain Stage 9. - -**Primary files:** old CLI parser/dispatch/inspection files and tests, -`internal/format`, documentation and maintained examples listed below. - -1. Remove obsolete `flag` parsing, comma mapping, old dispatch/help/exit - constants, legacy `render`/`inspect` commands, custom source DTOs and - inspection writers, custom prepared/definition presentation, and unused - CLI report helpers. Delete `internal/format` if it has no remaining consumers; - preserve `internal/report` for HTTP. Retire source/schema flags and the old - file/directory selector machinery; acquire the single framework document - through native APIs without resurrecting a framework facade. -2. Replace obsolete tests with selected native integration protection from - Stages 2–7. Retain architectural import boundaries and HTTP regression tests. - Do not make intentionally retired snapshots or aliases pass by retaining - production compatibility code. Avoid testing CommandKit's complete parser - or formatting matrix again in Scriptorium. -3. Update canonical owners with implemented behavior: - - | Owner | Required changes | - | --- | --- | - | `docs/cli.md` | New command tree, applicable flags/aliases, native selection/reporting, stdout redirection, separate report files with optional format selection, statuses, completion, explicit smoke tests. Link upstream for standard family details. | - | `docs/config.md` | Selected native discovery order and filenames; `promptkit.configuration` and `promptkit.schema_dir` replacing the source list and top-level schema root; removed render default; native overlay selection, overrides, scopes, and comparison. Preserve collection imports and document the separate framework file. | - | `docs/integrations/subprocess.md` | Artifact-first execution, native reports and result availability, content-bearing metadata reports, stream capture, partial delivery, cancellation, and caller responsibility. Link exact CLI syntax rather than duplicate it. | - | `docs/operations.md` | Updated discovery/preview/execution workflow, explicit smoke-test effects, potentially sensitive reports, file retention, server process lifecycle, unchanged HTTP limits. | - | `docs/internal/overview.md`, `adapters.md`, `sources.md` | Actual component inventory and data flow, native acquisition boundaries, CLI result versus retained HTTP observation report, selector/engine lifecycle. | - | `docs/development.md`, `docs/policy/architecture.md`, `docs/policy/testing.md` | Accurate component/dependency/reading and test ownership descriptions; retain adopted constraints, policy provenance, and accepted ADR decisions. | - | `README.md`, `docs/consumers/api.md`, `docs/consumers/upgrading-promptkit.md` | Current quickstart/navigation and any affected examples; distinguish framework-format migration from the new CLI migration. | - -4. Add a focused CLI migration guide under `docs/consumers/`, linked from the - CLI/consumer overview. Cover positional prompt selection; `render` and - `inspect` replacements; file versus literal inputs; repeated mappings without - comma splitting; native configuration discovery; the new `promptkit` settings - and removal of source/schema CLI flags; `--overlay` names; endpoint - and timeout spelling/units; - stdout redirection in place of output-file flags; separate native reports, - optional report-format selection and upstream automatic rendering, and result - availability; quiet behavior (omit quiet to capture main output); status - changes; and content-bearing native inspection/reports. - This prepares release migration information without selecting a version, - editing published notes, tagging, pushing, or adding release gates. Eventual - release notes must summarize the breaking change and link the guide under - the existing release/OSS policies. -5. Update maintained application configs to the new `promptkit` settings and - remove retired fields. Where an example previously selected multiple files - or directories, revise it to use a framework entry file and native import - semantics. Do not recreate the retired source-list precedence locally. - Update `examples/render-markdown-summary.sh`, `render-v0.9-features.sh`, - README/config examples, and collection workflows to native prepared preview, - inspection, positional IDs, and preferred aliases. Existing example script - filenames may remain; they are not CLI compatibility commands. Retain both - collection-entry spellings and the multi-definition discovery example. -6. Keep historical release notes unchanged. Update roadmap/Narratio status only - after their acceptance behavior is implemented and verified. Do not silently - retire deferred HTTP redesign or dynamic-resource completion proposals. - -**Evidence:** no production command routes to retired parsing/presentation; -remaining imports justify every retained helper/package. Maintained YAML loads -under the new schema, scripts run without provider access where intended, and -current documentation links resolve. Migration examples match the built CLI. - -## Stage 9: Verify The Complete Native Cutover - -**Status: Complete.** Verified the assembled native CLI on Go 1.27.4 with -`go test ./... -count=1`, `go test -race ./... -count=1`, `go vet ./...`, -and `go build ./cmd/scriptorium`. Formatting, diff whitespace, module tidiness, -shell syntax, maintained examples, and local Markdown links/anchors pass. -The maintained discovery configuration now has an end-to-end controlled-provider -test covering support/review inventories, requirements before artifacts exist, -concrete validation, preview/run context agreement, and independent native app -and framework comparisons. Existing checkout tests verify both optional entry -spellings and discovery on later invocations. Additional checks cover rejected -legacy surfaces, partial output, diagnostic delivery failure, and real child -process interrupt/SIGTERM cancellation reaching a provider request. - -Built Linux amd64 and arm64 with Go 1.27.4, `CGO_ENABLED=0`, `-trimpath`, -and `-s -w` plus version/revision linker metadata. The amd64 binary reports -the injected `verification` identity and full source revision -`bd7136ceebbdc7498e9a768ce8abbe0cbb00318f`; arm64 was cross-built, not executed. -The binary also exposes help, native scope discovery, and Bash/Zsh/Fish -completion without loading configuration or contacting a provider. - -Selected releases remain CommandKit v0.7.0 -(`b57bfe176cff05a892e6cb07ebb5f350239e55d4`), ckconfig v0.9.0 -(`9962368f0c1ea1f6ad010638e94621091105d745`), ckprompt v0.10.0 -(`c9a56e1b15f2169881a91fca4e1f4a1c475e057a`), ConfigKit v1.2.1 -(`51ef3144158db1a09fabdbd1c7ae59908c84923b`), and PromptKit v0.23.3 -(`804a4d32b23aa2e7973400bb0a322a7016574c9f`). Module and linked-runtime -inspection confirms no replacements, workspace, vendoring, or linked maintainer -tools; attribution follows the linked dependencies, including conditional -Windows mousetrap. Public native adapters, request bindings, reporters, -`RenderReport`, and typed outcomes remain the selected integration APIs. - -The final implementation audit against this plan and ADRs 0004–0006 found no -remaining required work. HTTP/report implementation and accepted ADRs remain -unchanged; no compatibility surface, post-resolution config rewriting, extra -readiness gate, workflow state, snapshot promise, or transactional delivery was -added. Embedded framework configuration, dynamic-resource completion, the -optional format accessor, and HTTP redesign remain outside this migration. -No release was published and no commits were pushed. - -1. Finish any deferred stage checks against the complete application. Use real - ConfigKit, PromptKit, and CommandKit with deterministic provider substitutes - at the external boundary. Tests remain offline and independent of real keys. -2. Run a representative end-to-end collection workflow using - `examples/config.discovery.yml`: discover resources in support/review, - show requirements before input artifacts exist, validate/preview once inputs - exist, and run through a controlled provider with consistent selections. - Include native app and framework configuration comparisons with independent - sides. Reuse the stage tests to cover Narratio's scenarios, not a parallel - test harness. Confirm both optional entry-file globs still work and a new - checkout is seen on a later invocation, not a hot-reload promise. -3. Verify reachable help/version, preferred/canonical aliases, completion - generation for the upstream-supported shells, and controlled smoke testing. - Help/version/scope discovery/static completion work without configuration or - provider availability. Confirm retired commands/flags are absent or rejected - except where a spelling now intentionally has its native meaning (`--input`). -4. Review the output/outcome matrix across stdout, caller redirection, report - files with automatic/explicit formats, quiet, completed validation failure, - operational failures, presentation errors, cancellation, and partial delivery. - Verify reports are native values with no Scriptorium wrapper, and HTTP's - distinct contract remains unchanged. -5. Run the repository baseline on the selected toolchain: - - ```sh - go test ./... - go test -race ./... - go vet ./... - go build ./cmd/scriptorium - ``` - - Check `gofmt`, `git diff --check`, affected examples and Markdown links, - `go mod tidy` cleanliness, and the selected module graph. Check linked - runtime packages separately with `go list -deps ./cmd/scriptorium` when - validating attribution. Build the existing Linux amd64/arm64 targets with - the unchanged release build options plus the selected identity metadata; - this is migration verification, not a new publication gate. -6. Audit the final diff against the roadmap and ADRs. In particular, confirm - no post-handoff effective-config rewriting, synthetic inspection evidence, - legacy CLI compatibility layer, new HTTP restriction, arbitrary secret - redaction, extra resource-readiness prerequisite, automatic provider probe, - workflow state, snapshot guarantee, or transactional file-delivery claim - was introduced. Upstream limits/semantics remain upstream-owned. -7. Record completion and the actual dependency/API selections after successful - verification. Commit the finished implementation units under the agent - policy and report checks, commits, and any remaining work accurately. Do - not mark the migration complete while required acceptance behavior is missing. - -Discovery, source selection, and schema controls are settled. The optional -selected-format accessor and deferred embedded framework configuration are not -migration dependencies or completion gates. - -[upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md -[upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md diff --git a/docs/roadmap/narratio-feature-request.md b/docs/roadmap/narratio-feature-request.md deleted file mode 100644 index 942104c..0000000 --- a/docs/roadmap/narratio-feature-request.md +++ /dev/null @@ -1,168 +0,0 @@ -# Prompt input requirements for Narratio - -Status: the native interface and consumer acceptance scenarios are implemented -and verified, including the assembled collection workflow. The -[implementation plan](implementation.md) records the verification evidence. -This proposal records Narratio's consumer needs and their mapping to the native -interface; the [CLI contract](../cli.md) owns current behavior. -The [CommandKit notepad](commandkit-notepad.md) records the migration decisions. - -## Consumer need - -Narratio produces transcripts, extraction outputs, and generated artifacts in -a staged pipeline. It binds named inputs to a Scriptorium prompt when generating -each analysis artifact. A Narratio source ID and a prompt input name are separate -identities: for example, the source -`narratio.transcript.final_trimmed_markdown` might be supplied under the prompt -input name `transcript`. - -Narratio needs to discover expected input names before running expensive -upstream stages and before the eventual input files exist. It can then show -operators how prompt inputs map to pipeline products and identify missing -bindings without reading prompt definitions or reproducing PromptKit's analysis. - -## Selected native operation - -Expose `scriptorium promptkit requirements show PROMPT_ID` through ckprompt. -Subprocess consumers select JSON with the standard `--format json` flag. -Default and explicit text output use the native YAML presentation. -The [upstream CLI contract][requirements-cli] owns syntax and report details. - -Use the same application configuration and framework source selection as -execution, including `--config` and `--overlay`. There are no application-defined -source/schema selectors. The preferred native aliases `--profile`, `--var`, `--session-id`, and -prompt/profile namespace flags supply the relevant discovery context. -Preserve upstream selection semantics, including the prompt's default profile -when an explicit profile is omitted. Qualified IDs identify installed resources; -there is no separate prompt-version selector or reported prompt-version field. - -The selected profile establishes identity, not execution readiness. Selecting -another profile does not itself change the prompt's discovered requirements. -Scriptorium's loading and request mapping must preserve the same effective -selection and applicable caller context across discovery and execution. - -Discovery requires no input bindings or output-artifact path. PromptKit performs -no artifact loading, schema loading, credential resolution, message rendering, -capacity reservation, or model call for this operation. Reading configuration -and prompt resources needed to build the captured engine is expected. The -[PromptKit discovery contract][requirements-api] owns the analysis and its -limits. - -## Native response and consumer interpretation - -Consume the native JSON report directly, without a Scriptorium-specific wrapper -or schema-version field. Successful report delivery writes one JSON document to -stdout, with diagnostics on stderr under CommandKit's standard reporting rules. -Consumers requesting a report should not enable quiet mode. - -| Field | Consumer meaning | -| --- | --- | -| `prompt_id`, `profile_id` | Exact selected resource identities. | -| `inputs` | Declared and recognizable template-referenced inputs, including exact `name`, requirement `kind`, `declared`, `content_type`, `description`, and `explanation`. | -| `variables` | Recognizable caller-variable keys with `name`, requirement `kind`, `supplied`, and `explanation`. | -| `complete` | Whether the supported dependency analysis is complete for the supplied context. | -| `issues` | Structured discovery limitations with a `code`, associated input or variable names where known, and a human-readable description. | - -PromptKit sorts input and variable entries by exact name, and deduplicates and -orders issues by their code and associated names. Preserve empty inventories -and false values. Input metadata distinguishes absent/null values from an -explicitly empty string. Explanations and issue descriptions are for display; -Narratio must use structured fields rather than parse their prose. - -The native input metadata includes content type and description. Current -PromptKit inputs have no per-input schema declaration to project. Do not infer -constraints from names or treat the output-validation schema as an input schema. -Variable `supplied` records exact-key presence, including an explicitly empty -value; this interface does not introduce a separate variable-default system. - -Requirements reports exclude artifact payloads, prompt contents, and unrelated -supplied variable values. A supplied value used to resolve an input identifier -can appear as that identifier. Keep this native behavior without adding a custom -projection of the report. - -The upstream report contract and adopted dependency versions govern the shape. -Migration documentation must identify relevant consumer changes; this proposal -adds no independent response-versioning mechanism or stronger compatibility -guarantee. - -## Conditional and incomplete discovery - -PromptKit classifies dependencies as required, optional, or conditional using -the supplied context and its supported template analysis. Recognizable references -only on known skipped paths can be optional. Explicit required declarations -still apply. Unavailable input contents, unresolved variable values or dynamic -names, and unsupported dependency-relevant constructs can leave discovery -incomplete. Valid templates are not rejected merely because the analysis cannot -fully resolve them. - -Narratio must inspect both the requirements and discovery completeness: - -- `complete: true` establishes discovery coverage, not satisfied bindings, - valid future input bytes, or execution readiness. Required inputs or missing - required variables may still be present. -- `complete: false` preserves useful findings and structured issues. An empty - partial inventory does not prove that no inputs are needed. -- A partial report can return status zero. An issue is not itself an invocation - failure. Narratio owns its policy for proceeding with incomplete dependency - information. - -Once input artifacts exist, native `promptkit requirements validate` can check -a concrete request through preparation. It is a separate operation and must not -replace early discovery. Neither operation guarantees later generation success. -Changes to configuration or resources between invocations can change findings. - -## Failures - -Use CommandKit's native nonzero outcomes and diagnostic messages for selection, -configuration, operational, and report-delivery failures. JSON report selection -does not turn diagnostic messages into a categorized JSON error response. -Narratio can attach the diagnostic to its own artifact or pipeline context; -it must not depend on parsing the message to recover a stable error category. - -Structured discovery issue codes belong to successful inspection reports and -are distinct from invocation failures. Follow PromptKit's distinction between -partial discovery and failures that return no inspection. Absence of a future -input artifact is not a discovery failure because discovery does not load it. - -The accepted consumer requirement is a nonzero return code plus failure -information. If programmatic failure categories or separate schema versioning -become necessary, discuss them upstream rather than introducing local wrappers. -Neither is a prerequisite for this migration. - -## Consumer acceptance scenarios - -1. A prompt requires `transcript`, but Narratio binds only `session_transcript`. - The native inventory identifies the exact required name before either file - exists, allowing Narratio to identify the missing binding. -2. A template references an undeclared input. Recognizable references appear in - the inventory with `declared: false`; unsupported dependency analysis is - explicitly incomplete rather than silently claiming full coverage. -3. An optional glossary is reported with its native classification, allowing - Narratio to distinguish it from a required binding. -4. Variables resolve a supported conditional dependency. Unknown conditions - retain conditional findings or discovery issues according to PromptKit. -5. Selecting another qualified prompt or profile reports the corresponding - identities. Prompt selection changes the analyzed definition; profile - selection alone does not change its requirements. -6. Discovery works with no generated input files, model access, or generation - credentials when the selected configuration and resources are readable and - valid for discovery. -7. An unknown prompt or invalid profile selection returns nonzero with native - diagnostics suitable for Narratio to associate with the affected artifact. -8. Narratio treats a complete report with missing required bindings differently - from a complete, satisfied dependency check, and handles partial reports - without assuming that status zero establishes completeness. -9. Scriptorium's adapter uses consistent configuration, namespaces, and applicable - request context across discovery, validation, preview, and execution. - -## Scope boundary - -Narratio owns its source catalog, stage ordering, source-to-input bindings, -artifact dependency graph, and session availability checks. Scriptorium exposes -PromptKit's native requirements through CommandKit. Narratio source IDs and -pipeline concepts do not become part of that interface. A graph renderer, HTTP -endpoint, batch operation, and changes to generation behavior are outside this -request. - -[requirements-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md#promptkit-requirements -[requirements-api]: https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/requirements.go diff --git a/docs/roadmap/policy.md b/docs/roadmap/policy.md deleted file mode 100644 index 66de1bf..0000000 --- a/docs/roadmap/policy.md +++ /dev/null @@ -1,223 +0,0 @@ -# Standard Repository Policy Alignment - -## Status And Intent - -Agreed and delivered on 2026-09-28. This roadmap replaces the -earlier licensing-only proposal with alignment of the complete applicable -policy set and its supporting documentation. It defines the targeted end state -and required changes. Its completed implementation plan is preserved in Git at -`git show 8b6c12f912b28ac00016f047f9846798a5de95d9:docs/roadmap/implementation.md`. - -The next release summary should mention the policy and licensing alignment, -the already-selected GPL-3.0-or-later application grant, and the separate -CC-BY-SA-4.0 treatment of adapted policy material. Version selection and -publication remain release preparation, not part of this delivery. - -The goal is identical policy language across adopting projects except where a -substantive, locally significant requirement or decision warrants customization. -Adopt upstream wording verbatim for non-substantive differences. Existing local -phrasing is not, by itself, a reason to retain a variation. - -## Review Revision And Current Baseline - -The fixed upstream review revision is -`d84a38ebab26f048cafbe59a2246700c35d29843`. -Use the [adoption and update guide at that revision](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md) -for this adoption. The review compared current local documents directly with -that revision; reconstruction or assessment of historical adoption baselines -is not required. - -The reviewed Scriptorium revision is -`d6aecf5c50269b7d130dbf19f416a67454cd9778`. It has six adopted policies, -without per-document Upstream Source metadata, and no `docs/policy/meta.md`. -The policy targets below supersede the earlier roadmap's narrower version -targets. - -| Policy and proposed Upstream Source | Current base | Target base | Target treatment | -| --- | --- | --- | --- | -| [agents.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/agents.md) | 1.1 | 1.3 | Adopt shared rules verbatim, including commit discipline. | -| [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md) | 1.1 | 1.3 | Adopt common principles and customize for Scriptorium's established boundaries. | -| [documentation.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md) | 1.4 | 1.11 | Adopt shared language and tailor the canonical topic map. | -| [testing.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md) | 1.1 | 1.3 | Adopt shared guidance with focused local test ownership. | -| [release.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md) | 1.2 | 1.4 | Adopt common rules and retain justified release choices. | -| [oss.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/oss.md) | 1.1 | 1.8 | Adopt licensing, attribution, and reference-example conventions. | -| [meta.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/meta.md) | Not adopted | 1.0 | Add provenance, local authority, and upstream discovery. | - -Every existing policy needs language and provenance updates. No adopted policy -is entirely update-free, but established application decisions, dependency -licenses, and release mechanics need no substantive change. - -Current supporting-document gaps include the README's obsolete BSD project -license statement, the release procedure's two-link footer, an attribution -document that does not follow the new exact House Format, and orientation -guidance that requires architecture reading even for unrelated work. -The architecture policy's command inventory also omits the implemented -`config` command family. - -## Target Policy Language And Local Customizations - -Remove every `Base Policy Template` section and its adoption instructions. -Replace instructional application-specific placeholders with actual decisions; -do not leave template examples describing nonexistent components. - -Use upstream common language verbatim. Keep necessary local requirements -clearly identifiable rather than paraphrasing entire shared sections. -The following customizations are justified: - -- **Architecture:** preserve PromptKit and ConfigKit ownership, full support - for valid PromptKit definitions, public dependency boundaries, HTTP artifact - containment, and simple predefined-prompt execution. Preserve caller-visible - request independence alongside shared engine and backend capacity state. - These are deliberate product and safety decisions, not generic template - choices. Adopt upstream architectural principles proportionately; they do - not require a wrapper or interface for every library. Correct the command - inventory and keep concrete package mechanics in internal documentation. -- **Documentation ownership:** tailor the topic map to the executable CLI and - HTTP application. Scriptorium does not offer a reusable public Go API; - consumer guidance covers executable use and migration to PromptKit. - PromptKit remains the owner of framework formats. Use upstream wording for - generic ownership, example, and ADR guidance instead of retaining redundant - local paraphrases. Preserve accepted ADR decisions and their history. -- **Testing:** retain a short project-specific ownership section distinguishing - Scriptorium's integration and adapter tests from upstream framework/parser - tests. This prevents duplication of PromptKit and ConfigKit test matrices. - HTTP containment and shared-capacity behavior justify focused adapter - coverage. Upstream observations about domain coverage are not quotas or a - hierarchy that displaces risk-based testing. -- **Release:** preserve branch-before-tag publication, annotated tags, - Linux amd64/arm64 binaries and checksums, and asynchronous artifact delivery. - Retain race testing because the server shares concurrent engine state and - source guards because local replacements, workspaces, or vendoring can hide - unpublished dependency substitutions. Keep gate rationale in policy and - concrete commands, targets, and publication choices in the release procedure. - Upstream's optional atomic-push approach does not require a new feature. -- **OSS:** use Scriptorium's actual GPL-3.0-or-later grant in the project - example. Preserve dependency grants and the settled House Format - interpretation for upstream notice links. The code grant does not extend - to separately licensed copied policy material. - -No agent-policy exception is needed: upstream already preserves the local -commit authorization and safety boundaries. Stylistic preferences, alternate -wording, and generic elaboration do not justify additional exceptions. - -## Provenance And Public Discovery - -When adoption lands, each of the seven policies records its target -`Base Policy Version`, actual local adoption date in `Last Updated`, and -`Upstream Source` pointing to the exact corresponding file linked in the -table above. Do not substitute a repository homepage, moving branch, another -policy's URL, or a historical source revision for that per-document link. -Retain accurate provenance in later local edits. - -The new local `docs/policy/meta.md` follows upstream language after removing -its template section. It establishes that adopted local policies govern the -repository and that upstream changes require deliberate adoption. Its public -discovery links remain current: - -- [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy). -- [Current adoption and update guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md). - -Adopted-source and example links remain commit-pinned. Preserve the valid -commit-pinned example links supplied in the selected OSS policy; their asset -revision need not be rewritten merely to match the policy review revision. -Public discovery and attribution in this agreed adoption supersede the earlier -instruction not to reference the policy repository. - -## Orientation And Selective Reading - -Adapt [the upstream agent orientation](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/agents/AGENTS.md) -into [root AGENTS.md](../../AGENTS.md), preserving applicable existing -code-discovery instructions. It points to the local contributor guide and -requires the agent policy before recommendations, planning, or implementation; -it does not require reading the entire suite by default. - -The [contributor guide](../development.md) gains the upstream Policy Reading -Guide table and associated selection rules, including the new meta policy. -Retain Scriptorium's task-specific contract guide alongside it. Architecture -reading becomes task-triggered rather than unconditional. Relevant policies -are read before governed decisions, multiple policies may apply, material -already available in context may be reused, and expanded scope triggers -expanded reading. Policy-reading triggers live here, not in the documentation -topic map. - -## Licensing And Attribution - -Follow the [canonical copied-policy attribution entry](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/policy-attribution.md). -Insert it directly beneath the prescribed attribution title and replace all -three placeholder URLs with the full review commit. Identify the actual -copied/adapted scope, including agent-orientation material and copied reading -guidance where used, rather than describing only policy files if additional -material is incorporated. Preserve creator, copyright, license, disclaimer, -and modification information through the supplied notices and links. - -Required supporting changes: - -- Add the complete, unmodified `docs/oss/licenses/CC-BY-SA-4.0.txt` from the - selected revision. -- Extend [COPYRIGHT](../../COPYRIGHT) to identify the adapted policy material - as CC-BY-SA-4.0 and point to attribution for exact scope. Preserve - Scriptorium's GPL-3.0-or-later code grant and existing [LICENSE](../../LICENSE). - Unrelated application documentation is not automatically relicensed. -- Reformat [attribution](../oss/attribution.md) to the v1.8 House Format: - `# Open Source Attribution Notices`, followed directly by component entries; - factual optional identification; supplied copyrights; SPDX expressions; - license/notice links with actual filename labels and terminal periods; - and `[Source](COMMIT_URL).`. -- Remove its introductory policy prose, missing-copyright filler, and - agent-authored license-scope explanations. Omit an unavailable copyright - field instead of explaining that none was invented. Preserve actual - required upstream notices, applicable license expressions, and imported - dependency revisions. -- Correct [README](../../README.md) to link its GPL v3 or later statement to - `COPYRIGHT`, followed by the attribution link. -- Update [the release procedure](../release.md) to use the prospective - `COPYRIGHT | LICENSE | ATTRIBUTION` footer, with absolute immutable-release - URLs for all three destinations. The existing hosted workflow continues - copying the checked-in release note unchanged. - -The documented CC-BY-SA arrangement is agreed for this adoption. Original -licensing-example formatting has upstream's CC0 permission; using it alone -does not require a separate attribution entry. Reproduced license texts and -third-party notices retain their own terms. - -## Local Materials And Upstream References - -Keep applicable adopted policies, Scriptorium's adapted root orientation and -developer guide, actual project notices, attribution entries, and required -license texts locally. - -Keep the upstream adoption guide, README, root AGENTS.md, developer guide, and -example collection upstream. Link to them as appropriate rather than copying -them into a parallel local handbook. The upstream `agents/AGENTS.md` is the -downstream orientation template, distinct from upstream's own root AGENTS.md. -Copy only needed standard license texts, not the entire reference collection. - -## Scope And Completion Criteria - -This work updates policy and supporting documentation. It does not change -application code, dependency versions or grants, release scripts, publication -mechanics, or accepted ADR decisions. No new scanner, recurring synchronization -check, license approval, publication-time network probe, or release gate is -introduced. Published releases, tags, notes, and assets remain unchanged. - -Completion means: - -- All seven policy files use the selected versions, accurate source links, - adoption dates, and upstream common wording, with template-only content - removed and local variations limited to the justified decisions above. -- Orientation and selective reading agree, and local links resolve without - depending on a sibling checkout. -- Policy attribution and document-license scope match the material actually - incorporated; required standard texts are complete and unmodified. -- README, attribution, release navigation, and still-operative roadmap - handoffs agree with the new conventions. Historical implementation evidence - remains available through the Git references in the implementation plan, - without making old footer directions current policy. The earlier - author-selected license change remains in the next release's preparation - context; publication remains separate work. -- Review checks the resulting rules, source/example URLs, notice facts, local - links, license-text fidelity, and final diff. Runtime tests are unnecessary - for documentation-only changes. A Git adoption record is sufficient; no - additional provenance database or recurring audit is required. - -There are no unresolved policy choices for this scope. diff --git a/docs/roadmap/promptkit-v0.9.0-adoption.md b/docs/roadmap/promptkit-v0.9.0-adoption.md deleted file mode 100644 index 91065ac..0000000 --- a/docs/roadmap/promptkit-v0.9.0-adoption.md +++ /dev/null @@ -1,352 +0,0 @@ -# Promptkit v0.9.0 Adoption Roadmap - -## Status - -Complete. This document records the delivered feature scope and targeted end -state. The completed delivery plan is preserved at -`git show e4405966c87c8a7843b340146e90cc1e515bef42:docs/roadmap/implementation.md`; -current behavior remains defined by -the canonical application contracts linked below. - -The durable product and integration boundary for this work is established by -[ADR 0004](../adr/0004-definition-boundary.md). This roadmap applies that -decision to Promptkit v0.9.0 and owns implementation scope and completion -status. - -## Objective - -Bring Scriptorium from Promptkit v0.1.0 to v0.9.0 and expose the newer -framework capabilities that fit Scriptorium's existing CLI, HTTP, -configuration, presentation, and process boundaries. - -Scriptorium must accept the complete Promptkit v0.9.0 feature set expressed by -directory-backed prompt, profile, and schema definitions. Application adapters -must not narrow that format contract by requiring request values that the -selected definition does not require or by omitting selection values needed to -address a valid definition. Promptkit's tagged -[framework format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.9.0/docs/formats.md) -remains canonical; Scriptorium must delegate parsing and framework validation -rather than reproduce those rules. - -The completed application will retain Promptkit as the owner of reusable -prompt execution, source formats, profiles, backend definitions, capacity, -inspection, generation, and validation. Scriptorium will continue to own -application configuration, command and HTTP contracts, error and exit mapping, -output presentation, and deployment policy. - -## Targeted End State - -When this roadmap is complete: - -- Scriptorium pins the released Promptkit v0.9.0 module without a workspace, - replacement, vendored source, direct catalog import, or Promptkit internal - import. -- Existing valid CLI, HTTP, configuration, prompt, profile, schema, and render - workflows remain supported subject to Promptkit's documented v0.2.0 through - v0.9.0 compatibility corrections. -- Every Promptkit v0.9.0 prompt and profile feature expressible in definitions - under Scriptorium's configured directory sources is usable through the - executable application, including prompts with no inputs and explicitly - selected prompt versions. -- CLI and HTTP requests can supply a direct non-secret session ID. -- HTTP requests and a presence-aware CLI flag can inherit, replace, or - explicitly clear reasoning effort. -- Prepared output, CLI run summaries, and HTTP result metadata expose effective - backend identity when Promptkit supplies one. -- HTTP capacity rejection has a stable Scriptorium-owned overload response. -- Application configuration can register reusable engine-scoped custom - backends, including bounded concurrency and queue policy, for selection by - Promptkit profiles. -- CLI users can inspect prompt and profile definitions without supplying - placeholder inputs or invoking a model. -- Scriptorium's contracts and examples point to Promptkit v0.9.0 and accurately - describe its current credential, validation-repair, provider-control, - message-role, backend, and source-validation semantics. - -## Feature Scope - -### Complete Prompt And Profile Definition Compatibility - -Scriptorium will treat the tagged Promptkit v0.9.0 format contract as one -indivisible downstream compatibility boundary. This includes prompt identity -and version selection, optional and required input declarations, message and -content-file templates, supported roles, cache control, session templates, -default profiles, output contracts, schemas, and repair budgets. It also -includes standalone and inherited profiles, built-in and custom backend -selection, endpoint overrides, execution controls, optional credential -environment sources, and JSON-compatible extra parameters. - -Most of this support is provided by passing configured prompt, profile, and -schema directories directly to Promptkit. Scriptorium will not independently -decode these framework definitions or maintain a field-level subset. Two -current adapter restrictions must be removed so the executable interfaces do -not reject definitions that Promptkit accepts: - -- `run` and `render` will accept an optional prompt-version flag and map it to - `promptkit.RunRequest.PromptVersion`; and -- `run`, `render`, and `POST /v1/runs` will permit omitted or empty input maps. - Promptkit will decide whether an input is required by the selected - definition or referenced template. - -The HTTP API already carries `prompt_version`; its mapping must remain covered -by adapter tests. CLI and HTTP callers may continue to supply extra inputs, -subject to their existing file, containment, and size policies. Removing the -application-level nonempty-input requirement does not weaken Promptkit's -declared-required-input or template-reference validation. - -Profiles that name built-in backend IDs require no application registration. -Profiles that name other backend IDs become fully usable through the custom -backend configuration in this roadmap. Profile inheritance and all other -profile-field resolution remain Promptkit responsibilities. - -This compatibility requirement concerns fields and behavior expressed in -Promptkit YAML definitions. Go-consumer construction alternatives such as -single-file sources, injected `fs.FS` sources, in-memory profiles, fallback -profile filesystems, and prepared-execution handles are library-integration -features and are not required merely to support the complete definition -format. - -### Promptkit v0.9.0 Compatibility Baseline - -Required dependency and source changes: - -- update `go.mod` and `go.sum` to select Promptkit v0.9.0 and its selected - OpenRouter and Rakestrawhome catalog dependencies; -- change Scriptorium's inbound HTTP reasoning-effort representation to preserve - Promptkit's pointer semantics; -- retain keyed Promptkit public struct literals and confirm no removed - `RunRequest.Metadata` use exists; -- update tagged Promptkit links and version references throughout Scriptorium; - and -- preserve Scriptorium's architecture guard against replacements, workspaces, - vendored Promptkit code, former facade packages, and Promptkit internal - imports. - -Required compatibility review: - -- verify application and maintained example endpoints satisfy Promptkit's - absolute HTTP/HTTPS endpoint rules; -- verify prompt content paths, file artifacts, identities, JSON documents, and - JSON-compatible extra parameters satisfy the v0.6.0 safety boundaries; -- verify maintained prompt roles are limited to `developer`, `system`, `user`, - and `assistant`; -- verify every positive repair budget is no greater than three and is paired - with `basic`, `json`, or `json_schema` validation; -- document that positive repair budgets authorize additional provider calls, - latency, token use, and cost; -- document that unset optional provider controls are omitted and that a zero - effective value can represent an unspecified provider control unless an - explicit request override supplied it; and -- update credential guidance for Promptkit's optional environment lookup - behavior, profile `api_key_env` semantics, and Scriptorium's prohibition on - raw API-key inputs. - -### Session And Reasoning Request Controls - -The CLI `run` and `render` commands will accept a direct session-ID flag and map -it to `promptkit.RunRequest.SessionID`. The value remains non-secret -application correlation metadata and is subject to Promptkit's normalization -and length rules. - -The HTTP run request will accept `session_id` and map it through the existing -strict DTO boundary. Successful HTTP metadata will report the effective -session ID when present. - -The CLI `run` and `render` commands will also accept a presence-aware reasoning -effort flag. Omission inherits the selected profile, a nonblank value replaces -it, and an explicitly supplied empty value clears it. The existing HTTP -`model.reasoning_effort` field will gain the same three-state behavior while -remaining a JSON string when present. - -These additions must not introduce raw direct API-key flags or fields. - -### Backend Identity And Capacity Outcomes - -Scriptorium presentation will expose `SelectedBackendID` and the effective -target's `BackendID` without deriving identity from endpoint text. Backend -identity will be included where applicable in: - -- prepared-run text and JSON output; -- the CLI run summary; and -- HTTP response metadata and effective model parameters. - -Endpoint-only profiles continue to have no backend ID, and empty identities -must remain distinguishable from registered built-in or custom backends. - -The HTTP adapter will classify `promptkit.ErrCapacityExceeded` separately from -provider generation failures. The target public outcome is HTTP `503` with a -stable `capacity_exceeded` code and a generic message. Scriptorium will not -invent retry timing or expose an untrusted diagnostic. CLI capacity rejection -continues to be a runtime failure, with a clear safe diagnostic and the -existing runtime-error exit status. - -The HTTP server will use one appropriately scoped Promptkit engine across its -requests so backend admission, active-generation limits, and queue capacity -apply across concurrent in-flight work. The server may retain the operational -state needed for those limits and for request cancellation and lifecycle -management. This does not create durable per-request, conversation, or resume -state. - -Scriptorium will continue to return generic public model-generation failures. -Promptkit `GenerationError` provider code, type, and message values will not be -added to the public HTTP response because they are untrusted and potentially -sensitive. - -### Custom Backend Configuration - -The strict Scriptorium application configuration will gain an optional custom -backend collection. Each entry will support the application-owned mapping -needed to construct a public `promptkit.Backend`: - -- backend ID; -- OpenAI-compatible endpoint; -- optional API-key environment-variable name; -- optional JSON-compatible request-wide extra parameters; -- non-negative concurrency limit; and -- queue capacity with presence preserved so omission and explicit zero remain - different. - -Raw API-key values will remain invalid. Unknown fields will remain errors. -Configured backends will be registered through `promptkit.WithBackend` during -engine construction and will be immutable and engine-scoped. Promptkit will -remain the canonical validator for backend IDs, endpoints, reserved request -parameters, capacity bounds, duplicate or reserved IDs, environment-variable -names, and JSON-compatible values. Scriptorium will add context appropriate to -its configuration error boundary without copying those framework rules. - -The collection will be configuration-file-owned. This roadmap does not add -per-backend CLI flags. Existing endpoint-only profiles remain valid, while -profiles may select configured custom backend IDs through Promptkit's existing -`backend` field. Promptkit's built-in OpenRouter and Rakestrawhome backends and -profiles remain available without Scriptorium registration. - -The application configuration shape is a `backends` mapping whose keys are the -backend IDs registered with Promptkit: - -```yaml -backends: - local-gpu: - endpoint: http://localhost:11434/v1 - api_key_env: LOCAL_GPU_API_KEY - extra_params: - provider_option: enabled - concurrency_limit: 2 - queue_capacity: 0 -``` - -`endpoint` is required for each entry. The other fields are optional. Omitted -`queue_capacity` uses Promptkit's default queue policy when concurrency is -bounded, while an explicit zero disables queuing. The configuration contract -and complete maintained configuration example will document this shape when -the feature is implemented. - -### Prompt And Profile Inspection CLI - -Scriptorium will add a CLI inspection command with prompt and profile modes. -The intended command family is: - -- `scriptorium inspect prompt`, backed by `Engine.InspectPrompt`; and -- `scriptorium inspect profile`, backed by `Engine.InspectProfile`. - -Prompt inspection will select an ID and optional version and report the -normalized prompt identity, opaque prompt hash, declared default profile, -declared inputs, and normalized output contract. It will not require input -artifacts, resolve a profile, load a schema, render templates, reserve backend -capacity, or contact a model. - -Profile inspection will select an explicit profile ID and report its resolved -effective target, backend identity, optional credential source name, and -whether a later request must provide credential configuration. It will not -read credential values, load a prompt, reserve capacity, or contact a model. - -Inspection will support deterministic Scriptorium-owned text and JSON output -and normal output-file handling. Scriptorium will define explicit output DTOs -rather than treating Promptkit inspection structs as stable wire formats. -Inspection failures will use existing public Promptkit error identities and -Scriptorium-owned CLI diagnostics and exit behavior. - -The prompt form accepts `--prompt`, optional `--prompt-version`, `--config`, -`--prompt-dir`, `--format text|json`, and `--out`. The profile form accepts -`--profile`, `--config`, `--profile-dir`, `--format text|json`, and `--out`. -Both forms reject positional arguments and default to text output independently -of `defaults.render_format`. Configuration discovery and CLI-over-file source -precedence match the existing command family. Prompt inspection requires an -effective prompt directory; profile inspection does not, because Promptkit's -built-in profiles remain inspectable without one. - -## Documentation And Example Changes - -Implementation of this roadmap requires coordinated updates to the canonical -owners of affected behavior: - -- `docs/cli.md` for session and reasoning flags, inspection commands, output, - prompt-version selection, optional inputs, and exit behavior; -- `docs/api.md` for `session_id`, effective backend/session metadata, reasoning - presence semantics, optional inputs, and the capacity response; -- `docs/config.md` for custom backend configuration and current Promptkit - credential and provider-default semantics; -- `docs/operations.md` for capacity and custom-backend operational guidance - where deployment handling is affected; -- `docs/internal/adapters.md` and `docs/internal/sources.md` for implemented - mapping and engine-assembly behavior; -- `docs/policy/architecture.md` and `docs/internal/overview.md` only if concrete - component responsibilities or durable boundaries change; and -- maintained examples for valid v0.9.0 prompt/profile formats and custom - backend configuration. - -Current-state documents must not describe these features as implemented until -the corresponding code lands. - -## Validation And Completion Criteria - -The roadmap is complete only when: - -- ordinary and race-enabled tests pass against the tagged Promptkit v0.9.0 - dependency; -- `go vet ./...` and `go build ./cmd/scriptorium` pass; -- Go formatting and `git diff --check` pass; -- the architecture guard passes with no workspace, replacement, vendor tree, - former facade, or Promptkit internal import; -- maintained render, custom-backend, session, reasoning, and inspection - examples execute successfully without real credentials or provider calls; -- CLI tests cover explicit and omitted prompt versions for prompt IDs with one - or multiple definitions; -- CLI and HTTP tests cover prompts with no declared inputs, omitted optional - inputs, missing required inputs, and template-referenced inputs; -- HTTP tests cover omitted, replacement, and clearing reasoning states; -- CLI and HTTP tests cover session propagation and invalid session handling; -- presentation tests cover registered and endpoint-only backend identity; -- HTTP tests cover capacity rejection independently from provider failure; -- concurrent HTTP tests demonstrate that one server's requests share backend - admission and cannot bypass capacity through per-request engine creation; -- configuration tests cover strict decoding, precedence, queue-capacity - presence, invalid backends, and secret-field rejection; -- inspection tests cover deterministic text and JSON, source selection, - output-file handling, safe credential presentation, and public error - mapping; -- all maintained prompt roles and repair budgets are valid under Promptkit - v0.9.0; and -- representative definition fixtures cover inline and file-backed messages, - cache control, session templates, every output validation mode, schemas, - profile inheritance, built-in and custom backends, execution controls, - credential environment names, and extra parameters without Scriptorium - independently parsing those fields; and -- affected documentation links and copyable examples validate successfully. - -## Explicit Non-Goals - -This roadmap does not include: - -- appended request messages in either executable interface; -- retained or durable prepared-execution handles; -- HTTP prompt or profile inspection routes; -- embedded application fallback profiles; -- single-file, injected `fs.FS`, or in-memory prompt and profile source - configuration; -- request-level output-contract replacement through the executable interfaces; -- public disclosure of structured provider error details; -- direct imports or configuration of Promptkit's external catalog modules; -- raw API-key configuration, CLI flags, or HTTP fields; -- durable run state, conversations, retries, archives, checkpoints, or resume; - or -- changes to Promptkit itself. diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md deleted file mode 100644 index 7fd3ecf..0000000 --- a/docs/roadmap/promptkit.md +++ /dev/null @@ -1,374 +0,0 @@ -# PromptKit v0.12.0 Adoption - -## Status And Intent - -Drafted on 2026-10-03; source-selection and framework-inspection decisions -confirmed by the maintainer on 2026-10-04. The PromptKit v0.12.0 adoption has -been implemented and delivered after the complete audit passed on 2026-10-04. -This document remains target and decision context, not an implementation-stage -log. Release preparation remains separate; no release version has been -selected or published. No significant decisions remain open within this scope. - -Adopt PromptKit's ConfigKit-native configuration boundary while preserving -Scriptorium's simple, request-independent execution model. As established in -[ADR 0004](../adr/0004-definition-boundary.md), valid prompt and profile -definitions for the selected PromptKit version should work without a narrower -Scriptorium field-level format. Library-only APIs are considered separately; -this upgrade does not turn Scriptorium into a workflow application. - -The maintainer selected a native source cutover and full framework configuration -inspection. The latter uses upstream's native redaction in this new interface -only. These are deliberate product choices, not requirements inferred merely -from new library APIs. - -## Reviewed Baseline And Upstream Target - -The reviewed Scriptorium source is commit -`bb5006517b6c27dcbe56074f1d97140bf0999c48`; the last release is v0.15.0. -The completed ConfigKit adoption selects ConfigKit -v0.5.0. PromptKit remains v0.11.2, with the OpenRouter and Rakestrawhome `/v2` -catalog modules at v2.20260926.0. - -Application configuration already uses one ConfigKit loading, inheritance, -resolution, validation, and inspection pipeline. Framework construction still -passes `prompt_dir` and `profile_dir` into the removed PromptKit directory -fields and registers application `backends` with `WithBackend`. Profile -inspection substitutes an empty prompt filesystem to avoid loading prompts. -Maintained prompt/profile files and inline test fixtures use the old embedded -`id`, `version`, and `base_profile` syntax. - -The target is the published PromptKit v0.12.0 release at full commit -`4b8169da286917fde7875425bb32b799b12c6af3`. The published tag and downloaded -module identify that same revision. Canonical references are: - -- [Release notes](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/releases/v0.12.0.md). -- [Framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/formats.md). -- [Consumer and migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/consumers/pkg-promptkit.md). -- [Configuration ownership decision](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/adr/0001-configuration-boundary.md). - -PromptKit now also selects ConfigKit v0.5.0, so no further ConfigKit upgrade is -needed. Go 1.25.5 remains sufficient. Its catalog selections are: - -| Module | Version | Full source commit | -| --- | --- | --- | -| `promptkit-backend-openrouter/v3` | `v3.20260930.0` | `f17d208cb7ad1fb043cda2266cd3011d11b40aa0` | -| `promptkit-backend-rakestrawhome/v3` | `v3.20260930.0` | `993443d88c451901f4c917fa00c204fd3b54d28d` | - -This review examined upstream contracts and the affected Scriptorium adapters, -configuration, presentation, examples, and tests. It did not establish that the -unmodified application builds against the new, incompatible construction API. - -## Targeted End State - -### Framework Ownership And Source Assembly - -Scriptorium constructs engines through PromptKit's public root package and -`Config.Sources`. ConfigKit owns source composition, overlays, inheritance, -presence, null values, and resource origins. PromptKit owns final definition -validation, catalog contributions, backend completion, content capture, -preparation, execution, and capacity coordination. - -An operator-selected source may contain any combination of keyed `backends`, -`profiles`, and versioned `prompts`. Do not partition or filter documents by -directory name, filename, or a Scriptorium copy of the framework schema. -Do not independently preflight domain fields in lower-priority definitions -that the final effective configuration replaces. Syntax and composition -failures remain upstream loading failures. - -The selected application interface is an ordered `promptkit_sources` sequence. -Each entry selects either a `file` or a `directory` and contributes one caller -underlay, from lowest to highest priority. A directory uses -`promptkit.DirectoryInputs` and strictly composes its recursively discovered -YAML files. A file uses `configkit.File` -with declared imports enabled, so an entry document can compose fragments. -All caller groups follow PromptKit's maintained catalogs and owned defaults. -No separately exposed `Sources.Main` setting is needed for this interface. - -For example, the target application shape is: - -```yaml -promptkit_sources: - - directory: ./examples/prompts - - directory: ./examples/profiles - - file: ./deployment/promptkit.yml -schema_dir: ./examples/schemas -``` - -Directories retain the helper's default of disabled imports. Enabling imports -while also recursively discovering their YAML targets would include those -files twice in the same group, which ConfigKit rejects. Use a selected entry -file with imports for that layout; do not silently deduplicate, skip files, or -convert composition conflicts into precedence. - -Under this decision, `prompt_dir`, `profile_dir`, application `backends`, -and their directory flags are replaced, not retained as a second configuration -model. Framework backend definitions live with the framework sources rather -than passing through Scriptorium's scalar backend schema. A repeatable -`--promptkit-source PATH` selects a replacement ordered source list for -engine-using commands; each path selects a regular file or directory using the -same rules. Only an explicitly supplied flag overrides the configured list. - -Application source discovery, its imports and selected overlay, explicit CLI -override handling, and working-directory-relative application paths remain -unchanged. `--config-overlay` still selects an application overlay; it does not -implicitly select a PromptKit layer or profile. Framework priority is explicit -in the source list, with import/resource containment supplied by upstream for -each selected root. This is not a new global filesystem sandbox. - -### Complete Definition Support - -The target accepts the keyed v0.12.0 formats without compatibility rewriting: -profile and backend IDs are mapping keys, prompt IDs contain keyed string -versions, and `extends` replaces `base_profile`. Literal IDs and references -retain their exact spelling, including punctuation and meaningful whitespace; -filenames do not establish identities. - -All supported prompt/profile fields continue to reach PromptKit, including -inputs, message roles and cache metadata, inline and file content, session -templates, output validation and repair, backend/endpoint selection, -credentials by environment name, generation controls, and provider parameters. -The upstream format reference, not this list, owns the complete contract. - -Presence must survive the boundary: omission, explicit zero/false/blank, and -null are not interchangeable. Inheritance and layers recursively combine maps; -an empty map does not clear inherited entries. Backend defaults apply after -effective profile inheritance. Changing a model or backend no longer drops -unrelated explicitly inherited settings. Profile null suppression and explicit -zero controls must affect outbound requests as specified upstream. - -Partial profiles remain valid when request overrides can complete them. -Scriptorium must not introduce a mandatory model, credential, default profile, -or directory prerequisite that prevents such a request. With the selected -source interface, engine construction may have no prompt collection; missing -request selections fail through PromptKit's ordinary public errors rather than -a required `prompt_dir` check. Source selection does not imply provider access -or credential availability. - -### Captured Definitions And Runtime Lifecycle - -Engine construction validates every final effective definition, including -unused entries, and captures message-file content and static template syntax. -Invalid unused definitions or unreadable message resources may therefore fail -startup or inspection before a request selects them. An overwritten domain -value is not independently rejected merely because it appears in history. - -ConfigKit's structural directives now also apply to framework input mappings, -including dynamic provider maps. Document the reserved `extends` key and the -difference from literal runtime provider parameters; do not invent a quoting -escape or a second inheritance resolver. - -Content files use their effective field's source context, including imported -and inherited content. Retain those contexts by passing actual upstream -inputs; do not flatten files into synthetic mappings that lose origins. -Application paths remain working-directory-relative, whereas framework message -resources follow PromptKit's source-relative contract. Schema and request -artifact reads remain preparation-time resources; credentials and provider -operations retain their documented runtime boundaries. - -A server retains one constructed engine across its requests, with shared -backend capacity and queue accounting. Definition/message edits require a new -engine; for this scope, restarting the server is the supported way to obtain -one. CLI invocations naturally construct fresh engines. No file watcher, -reload endpoint, per-request server reconstruction, or durable state is added. -This is not a transactional snapshot of all external files or credentials. - -### Definition And Application Inspection - -`inspect prompt` and `inspect profile` use the same selected configuration -snapshot as execution. Remove the empty-prompt-filesystem substitution. -Profile inspection still does not need request inputs, schema reads, model -calls, or credential values, but constructing its engine now validates and -captures all selected definitions, including prompts. A partial target may be -inspected without imposing preparation's completeness requirements. - -`config validate`, `show`, `sources`, and `explain` remain application -configuration operations without constructing an engine. Under the selected -source cutover, they show source selections rather than the contents of -PromptKit's separately loaded definitions. They are not framework validation. -The separate framework inspection family below supplies framework validation -and captured provenance. - -### Captured Framework Configuration Inspection - -Add the CLI command family `inspect configuration` with `validate`, `show`, -`sources`, and `explain` operations. It uses the same application settings, -source selections, and engine construction as other engine-using commands, -without requiring a prompt/profile selection or request inputs. Each invocation -constructs one engine; reporting uses that engine's captured public view rather -than loading definitions again. - -- `validate` succeeds when the engine constructs successfully and produces no - success report. It validates final definitions and captures message resources, - not provider access, credential availability, or request-specific preparation. -- `show` writes the captured effective YAML through - `ConfigurationInspection.WriteEffective`. -- `sources` presents structured JSON source records from - `ConfigurationInspection.Sources`, including the source kinds, layers, and - underlay positions needed to distinguish maintained and operator inputs. -- `explain --path JSON_POINTER` uses the native explanation view and writer - for effective values and history. Root and literal mapping-key paths follow - the same JSON Pointer conventions as application `config explain`; IDs with - slashes or punctuation must not become dotted-path lookups. - -Use PromptKit's public `InspectConfiguration` and its native writers and -records. Surface applicable load diagnostics safely on stderr; successful -reports go to stdout. Inspection does not resolve credential values, contact -a provider, or watch/reopen sources after construction. Captured effective -configuration is distinct from backend-completed `inspect profile` output and -request-specific prepared output; none substitutes for the others. - -The maintainer explicitly accepts upstream's credential-shaped provider-key -redaction for this new family, including effective and historical values. -Fields such as `token` and `password` can therefore be redacted here while -remaining visible in existing profile/prepared views. This is not blanket -redaction of `extra_params`, a change to parameters sent to providers, or a -change to existing inspection interfaces. Environment-reference names and -ordinary unclassified content can remain visible. Reports may contain prompt -text, provider data, paths, and identifiers; native redaction is not a promise -that the output is safe to disclose. - -### Requests, Presentation, And Disclosure - -Keep CLI/HTTP request independence, presence-aware execution overrides, -generation/whole-run timeout separation, transient retries, execution reports, -artifact policy, and public error mapping. Preserve existing serialized results -unless an upstream change actually requires an application contract change. -Prepared/profile numeric values alone are not proof that a zero control was -sent; verify upstream presence through generation or recorded outbound requests. -The dependency change alone does not require a new presence DTO. Continue -mapping errors by public identity rather than message text. - -Environment-variable names remain visible; resolved API keys are never -printed or serialized. Ordinary `extra_params` retain their selected visibility -where those values are presented. Moving definitions out of application -settings changes what `config` can inspect, not their sensitivity classification. -Do not silently adopt broader redaction rules for existing profile/prepared -inspection. - -## Work Needed From The Baseline - -- **Dependencies and attribution:** select released PromptKit v0.12.0, tidy the - module graph, and use its selected `/v3` catalogs without direct application - imports. Remove obsolete `/v2` modules and `gopkg.in/yaml.v3` if no remaining - imports require them. Update PromptKit/catalog component entries and exact - source, COPYRIGHT, and LICENSE links in `docs/oss/attribution.md`. The reviewed - grants remain LGPL-3.0-or-later for PromptKit and MIT for the catalogs; reuse - the applicable local license texts. Preserve unrelated attribution entries - and historical release documents. -- **Application settings and CLI:** implement the selected source interface - through `internal/config` and shared CLI override mapping. Retire the backend - document/runtime conversion and old directory fields, add ordered source - selection, and update command help and prerequisites. Application validation - checks its schema and selector shape; - framework acquisition and domain validation belong to engine construction. -- **Shared engine wiring:** replace removed fields/options with upstream - inputs and underlays, retain `SchemaDir`, `TransientRetries`, and runtime - collaborator injection, and use the same construction path for execution, - rendering, definition inspection, and serving. Preserve identifiable - PromptKit and ConfigKit causes and safe diagnostics. Remove obsolete - prompt-filesystem inspection scaffolding. -- **Captured framework inspection:** add the `inspect configuration` family - with `validate`, `show`, `sources`, and `explain` using the shared engine path - and its public captured inspection view. Reuse native YAML/explanation writers, - preserve useful source-layer information in JSON presentation, and keep application - `config` independent of framework loading. Apply the approved native - redaction exception only to this new family. -- **Definitions and fixtures:** migrate every maintained prompt/profile file - under `examples/` and `testdata/`, and inline definitions and construction - helpers in CLI, HTTP, and formatting tests. Replace old inheritance syntax - and move backend examples into framework definitions. Review old explicit - zeros for their changed meaning instead of preserving obsolete expectations - mechanically. Keep useful feature-adoption coverage; filenames need not be - renamed merely to reduce historical naming. -- **Focused adoption coverage:** use real ConfigKit/PromptKit boundaries for - representative source order, same-group conflicts, file imports, combined - documents, inherited source-relative content, exact IDs/version selection, - null suppression, explicit zero/false, and partial-profile completion. - Verify eager failures for unused final definitions and unchanged captured - message content after file edits on an existing engine. Retain shared-server - capacity, retry, cancellation, restricted artifact, output, and error tests. - Cover framework inspection's effective YAML, source layers, literal-key - explanations, diagnostics, and effective/historical native redaction without - provider calls. Protect the distinction between application validation and - framework validation, and unchanged visibility in existing profile/prepared - inspection. Avoid snapshots of incidental writer prose. - Own integration risks locally without recreating upstream's exhaustive parser - or inheritance matrices; use offline clients or `httptest` for generation. -- **Current documentation and migration guidance:** update owning contracts - in `docs/config.md`, `docs/cli.md`, and `docs/operations.md`, affected internal - docs, `docs/development.md`, architecture version/ownership references, - README, examples, and applicable consumer guidance. Link to v0.12.0 framework - contracts rather than copying their specification. Correct statements that - ConfigKit does not participate in framework loading. Explain the selected - source migration, framework-inspection command family and scoped redaction - exception, and engine-rebuild requirement. Preserve accepted ADR - decision content. Update HTTP docs only where observable behavior changes. - -## Compatibility And Release Impact - -This is an intentional breaking adoption, not a patch-only dependency refresh. -Users must migrate definitions, inheritance syntax, source assembly, and -assumptions about numeric presence, recursive maps, eager validation, and file -reload. Under the selected native interface they must also migrate the -application source selectors and move application backend definitions into -PromptKit source files. Provide small before/after examples and runnable -offline migration checks when implementation lands; no automatic legacy parser -or catalog alias layer is proposed. - -PromptKit's maintained profile IDs remain supported, not frozen to fixed model -settings. Review used external catalog IDs against the selected catalogs; do -not promise live provider availability or preserve every volatile inventory ID. -Hashes remain opaque equality values, not cross-version identity guarantees. - -Under the [release policy](../policy/release.md), the eventual release must be -a new pre-1.0 minor version. Do not select or publish a release in this work -set. The previously completed ConfigKit work may share that release; final -version, notes, and roadmap retirement belong to release preparation. - -## Completion Criteria And Scope Limits - -Adoption is complete when the released dependency graph is selected, the -approved source interface reaches the canonical framework boundary without -losing definition semantics, maintained examples and fixtures use v0.12.0, -and CLI/HTTP workflows and inspection meet the target above. The new framework -inspection family must use captured native reports with its explicitly scoped -redaction behavior, without changing existing inspection disclosure. Run the -existing development checks, affected offline examples, and link/diff checks, -with focused new integration tests for the actual migration risks. - -This work does not add conversations, appended/follow-up messages, -prepared-handle coordination, semantic retry workflows, embedded configuration -bundles, framework internals, or application-owned framework validation. -Library availability alone does not justify additional commands, endpoints, -resource controls, recurring upstream probes, or release gates. Deferred -interfaces are scope choices for this adoption, not permanent prohibitions. - -## Confirmed Decisions - -### Native Source Cutover - -The maintainer accepted the ordered `promptkit_sources` file/directory interface -and moving backend definitions out of application settings. This exposes -combined definitions, explicit priority, imports, and full presence/null -semantics through their canonical owner. It removes duplicated backend -representation and avoids translating absent scalar fields into presence-aware -overlays. The deliberate application schema and CLI migration accompanies the -unavoidable framework format migration. - -Retaining the old directories and application backend surface was considered -but not selected: it would reduce migration while retaining duplicate backend -configuration, presence/null translation, and a less flexible source interface. - -### Native Framework Inspection With A Scoped Redaction Exception - -The maintainer selected `inspect configuration` using the captured native view, -including upstream redaction in this new interface only, rather than deferring -the feature. Provenance and history make layered configuration easier to -diagnose, and native writers avoid maintaining a parallel representation. - -The accepted tradeoff is different provider-parameter visibility between this -new view and existing profile/prepared inspection. Existing API-key-only -redaction choices remain otherwise unchanged. Deferral or an upstream -consumer-selectable sensitivity API could avoid that difference, but neither is -a prerequisite for this adoption. Do not reconstruct private configuration to -bypass native writers or depend on an unpublished upstream interface. diff --git a/docs/roadmap/upgrade-kit.md b/docs/roadmap/upgrade-kit.md deleted file mode 100644 index 5befeaa..0000000 --- a/docs/roadmap/upgrade-kit.md +++ /dev/null @@ -1,274 +0,0 @@ -# Promptkit v0.11 Adoption - -## Status And Intent - -Accepted feature direction, recorded on 2026-09-26. Implementation is complete -to the pre-release boundary; version selection, release-candidate validation, -and publication remain separate release preparation. The baseline descriptions -below record the state when this roadmap was written, not current behavior. -Upgrade directly from Promptkit v0.9.0 to v0.11.0, including the intervening -v0.10.0 catalog transition. This document defines the desired end state and -the changes from the current baseline. The historical plan at -`git show 43eea5c7c41d2a8134b3dece60f3af5c98b8fd1c:docs/roadmap/implementation.md` -owns sequencing, concrete interface choices, verification steps, and unresolved -implementation decisions. - -The target is complete definition compatibility, controllable transient -retries, an optional whole-run deadline, and modest opt-in execution diagnostics. -This is a focused adapter and configuration update, not another architecture -migration. Optional diagnostics are included in the desired feature set. -“Optional” means callers opt in, not that diagnostics may be silently omitted -from the completed adoption or appear in default output. - -[ADR 0004](../adr/0004-definition-boundary.md) and the -[architecture policy](../policy/architecture.md) govern scope. Promptkit remains -the parser, validator, execution engine, and owner of framework defaults. -Scriptorium remains a simple executable application for independent prompt -executions, with shared operational state where required for backend limits. - -## Baseline And Upstream Changes - -Scriptorium currently selects Promptkit v0.9.0 and the v1.0.0 backend catalog -modules. It already supports CLI execution, rendering, prompt/profile -inspection, HTTP execution, configured backends, and presence-aware execution -overrides. It does not expose transient retry settings, a whole-run deadline, -or execution observers. CLI execution currently supplies a background context. - -The upstream review covered the local tagged release v0.11.0 at commit -`db05b56166ca2d8650dfaf660e1cf0eed3932e1d`. Its canonical references are: - -- [v0.10.0 migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.10.0/docs/releases/v0.10.0.md); -- [v0.11.0 release notes](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/releases/v0.11.0.md); -- [definition formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md); -- [execution and retry integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/integrations/openai-compatible-chat.md); -- [consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md); and -- [observation declarations](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/observations.go). - -A diagnostic run using a temporary module file compiled Scriptorium against -v0.11.0. The existing test suite reported one failing profile-inspection case -that selects the removed `deepseek-4-flash` profile; other packages passed. -This establishes an initial migration issue, not proof of complete behavioral -compatibility or coverage of the new capabilities. The diagnostic did not -change the repository dependency pin. - -Neither intervening release adds declarative prompt/profile fields requiring -new adapter plumbing. The definition-facing changes concern catalog contents -and resolution precedence. Retry and observer APIs are execution controls; -their adoption is a deliberate case-by-case choice under ADR 0004. - -## Dependency And Definition Compatibility - -### Target End State - -Scriptorium uses tagged Promptkit v0.11.0 through its supported root package, -with the catalog versions selected by that release: - -- `promptkit-backend-openrouter/v2` v2.20260922.1; -- `promptkit-backend-rakestrawhome/v2` v2.20260922.0. - -Valid definitions for the selected Promptkit version remain usable through -Scriptorium's existing sources and adapters, subject to its established HTTP -artifact and deployment boundaries. Rendering and inspection remain offline -operations that do not generate model output. - -The maintained names `promptkit-openrouter-standard` and -`promptkit-openrouter-auto` work wherever a profile ID is accepted, including -prompt defaults, explicit selection, inheritance, and profile inspection. -They are opt-in choices, not new Scriptorium defaults. Ordinary custom-source -precedence remains intact. - -A stable maintained name is not a frozen model/settings selection. External -catalog entries can change or disappear across upgrades; inheriting from one -does not create a frozen copy. Complete application-owned profiles remain the -appropriate choice when an application owns its model and settings. - -### Change From Baseline - -The module graph and active definition fixtures reflect the released v0.11 -catalogs rather than v0.9's catalogs. The selected catalog removes -`deepseek-3-2`, `deepseek-4-flash`, and `deepseek-4-pro`; newer DeepSeek names -are not compatibility aliases. Migration guidance offers an available catalog -profile, a maintained Promptkit name, or a complete application-owned definition. -Application-owned examples retain fixed settings where that is their purpose. - -Definition conformance and focused resolution coverage protect Scriptorium's -adapter boundary without duplicating the upstream parser or catalog. Existing -dependency boundaries also apply to the new `/v2` module paths. - -## Controllable Transient Retries - -### Target End State - -Expose `transient_retries` in application configuration, with a CLI execution -override and an HTTP request override. Preserve value presence throughout: - -| Value | Meaning | -| --- | --- | -| Omitted | Inherit the engine setting, ultimately Promptkit's default. | -| Zero | Disable additional transient attempts. | -| Positive integer | Permit that many additional transient attempts. | -| Negative integer | Invalid configuration or request. | - -Adopt Promptkit's default of two additional attempts rather than silently -pinning the previous single-attempt behavior. Users must be able to select zero -explicitly. Request overrides take precedence over application configuration; -omission must not accidentally become an explicit zero. - -Promptkit alone owns eligible statuses, attempt execution, backoff, -`Retry-After`, and capacity coordination. Scriptorium adds no outer model retry -loop. Transient retries and structural repairs have distinct budgets: each -generation, including each repair generation, receives its transient budget. -Retries do not imply exactly-once generation or complete billing knowledge. - -### Change From Baseline - -Application settings reach `promptkit.Config.TransientRetries`, including the -shared server engine, and request overrides reach -`promptkit.RunRequest.TransientRetries`. This adds execution controls, not -prompt/profile schema fields or provider model parameters. Strict decoding and -presence-aware mapping preserve inheritance and explicit zero. User and -operations guidance makes the changed default, latency/cost implications, and -independent repair budget visible. Cancellation and shared backend limits -remain effective during retrying executions. - -## Optional Whole-Run Deadline - -### Target End State - -Callers can opt into a total execution deadline independently of the existing -generation timeout. No new default deadline is imposed. Existing timeout -controls must not silently change meaning: in v0.11.0 they apply per generation -attempt, whereas a whole-run deadline bounds the overall operation, including -preparation, capacity waiting, retry delays, attempts, and repairs as supported -by the upstream context contract. - -Expose this choice through CLI execution and HTTP execution. Derive any timeout -context from the caller's existing context, so a caller cancellation or earlier -deadline still wins. This is a cancellation boundary, not a guarantee of -instantaneous interruption of arbitrary callback or filesystem code. - -### Change From Baseline - -CLI execution can carry a selected deadline instead of always using an -unbounded background context. HTTP execution can shorten the incoming context -without losing parent cancellation or changing server lifecycle behavior. -Total-run duration handling is separate from existing attempt-timeout conversion. -The interval covers the engine invocation, not adapter parsing, engine creation, -or output writing. Provider retry timing can exceed local backoff limits; -per-attempt timeouts do not cap that complete invocation. - -## Opt-In Execution Reports - -### Target End State - -Provide a modest terminal execution report for CLI and HTTP callers who opt -in. Capture selected metadata through `RunRequest.Observer`, including attempt, -retry, repair, timing, outcome, and presence-aware usage information. Reports -should be available for completed successful and failed execution invocations -when Promptkit supplies terminal observations. Do not invent execution data for -failures that occur before invocation. - -Keep generated CLI content on stdout or the existing output path. Execution -reports use a separate destination. Ordinary CLI output and HTTP response -shapes remain unchanged when reporting is not requested. - -The report has a Scriptorium-owned schema rather than serializing upstream -events directly: `ExecutionEvent` has no stable JSON contract. Preserve unknown -usage versus reported zero, and incomplete versus complete observed totals. -Existing successful-result usage semantics remain unchanged. A terminal total -is an aggregate, not another attempt to add to the bill; no report is a billing -ledger. - -### Change From Baseline - -Both adapters have opt-in reporting and explicit application-owned report DTOs. -Per-request collection adds no shared mutable report state, durable storage, -callback I/O, or event archive. Operational failures can carry reports without -manufacturing partial `RunResult` values. Default output remains unchanged. - -Reports exclude prompt and response bodies, credentials, headers, endpoint URLs, -provider diagnostic text, and raw errors. Selected identifiers remain potentially -sensitive even when observations are content-free. Reports are concise terminal -metadata, not a general telemetry framework, event stream, or durable history. - -## Errors And Compatibility - -Preserve existing CLI exit classifications and HTTP `502 / llm_failed` -classification for generation failures. Keep safe public messages rather than -exposing provider error bodies or parsing diagnostic strings. - -Promptkit adds `ErrTransport`, `ErrMalformedResponse`, `ErrRetriesExhausted`, and -`RetryExhaustedError`. Use their public identities to support optional structured -failure details in execution diagnostics, including actual attempts where -available. Retry exhaustion and the final cause are distinct facts; do not lose -the underlying failure category by flattening them into one label. - -Capacity and validation behavior remains intact. Whole-run deadline and caller -cancellation outcomes are deliberate adapter classifications, distinct from a -provider-attempt timeout while the caller context is still live. The implementation -plan owns the exact presentation choices. Existing generation-error codes do -not need a breaking replacement for this upgrade. - -## Licensing And Distribution Review - -Promptkit v0.11.0 changes from GPLv3 to LGPL-3.0-or-later. Scriptorium's current -binary workflow produces statically linked Go executables, and upstream's -[license summary](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/README.md#license) -explicitly calls out distribution considerations for that model. Catalog and -other dependency licenses remain separate. - -Before distributing the upgraded binaries, resolve the applicable notices, -license texts, source availability, and any required materials or permissions -for recombination with a modified library. Record the chosen distribution -approach and make any corresponding packaging/documentation changes. This -roadmap is not a legal determination or a complete compliance checklist. - -Do not automatically relicense Scriptorium, assume that library source alone -settles every distribution requirement, or alter historical release contents. -Licensing review is a concrete adoption prerequisite, not a new blanket manual -approval gate for every future release. - -## Documentation And Delivery - -Current documentation links to the selected v0.11.0 contracts once implemented. -CLI, HTTP, configuration, and operations documents own their respective new -behavior; internal docs explain adapter mapping; release notes summarize -compatibility impact. Historical release notes and ADR decision content remain -unchanged. Current examples and migration guidance reflect the selected version. - -The upgrade merits a minor Scriptorium release, not a compatibility patch, -with prominent migration guidance for removed profiles, changed retry behavior, -the explicit single-attempt option, and timeout layering. Any later decision to -defer part of the target leaves that feature visibly incomplete until delivered. - -Use the existing [release policy](../policy/release.md) and -[runbook](../release.md). This roadmap authorizes no publication. No new ADR is -needed unless a later decision changes the established product or compatibility -boundaries. - -## Completion Criteria - -- The tagged dependency and selected catalog modules are adopted without - unsupported imports or local dependency substitutions. -- Existing definition conformance tests and focused maintained-profile tests - pass; removed profile IDs have explicit migration guidance, not silent aliases. -- Retry settings preserve omission and zero across configuration, CLI, and HTTP; - Promptkit remains the sole retry/capacity implementation. -- Optional total deadlines bound the caller operation without redefining - per-attempt timeouts or disabling parent cancellation. -- Opt-in terminal reports provide safe, isolated, presence-aware execution - metadata without changing default output or creating durable workflow state. - Any deferred reporting work remains visibly incomplete. -- Existing error classifications remain compatible, with deliberate handling - of the new public identities and context outcomes. -- The licensing/distribution approach is resolved before upgraded binary - distribution, and any required materials are included in the chosen workflow. -- Affected current contracts, examples, and migration guidance match - implemented behavior. Relevant tests remain offline and credential-free, - and normal development validation passes. Release-candidate validation and - the version-matched note remain release preparation. - -Concrete interface decisions and the selected distribution approach are recorded -in that completed historical plan. They do not expand -the product into conversations, follow-up messages, application-owned semantic -retry loops, prepared-handle coordination, or multi-step workflows.