Retire completed roadmaps and preserve future work
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
27
docs/roadmap/future.md
Normal file
27
docs/roadmap/future.md
Normal file
@@ -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.
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user