Retire completed roadmaps and preserve future work

This commit is contained in:
2026-11-20 15:16:33 +00:00
parent f5573f7c8f
commit 857c0bae20
11 changed files with 34 additions and 2910 deletions

View File

@@ -49,5 +49,6 @@ instead.
Standard inspection exposes the upstream result without constructing a different Standard inspection exposes the upstream result without constructing a different
effective document, reconciling separate explanation trees, or reinterpreting effective document, reconciling separate explanation trees, or reinterpreting
upstream paths. The [adoption roadmap](../roadmap/commandkit-adoption.md) tracks upstream paths. The completed
implementation. [adoption record](https://forge.maximumdirect.net/eric/scriptorium/src/commit/f5573f7c8f2ddf0d69414a05c978c8d6cfe291e7/docs/roadmap/commandkit-adoption.md)
remains in Git history.

View File

@@ -2,7 +2,7 @@
**Base Policy Version:** 1.3 **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 **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 parsing, presentation, and outcome mechanics; application commands and effects
remain local. Standard configuration inspection uses native adapters without remain local. Standard configuration inspection uses native adapters without
custom effective documents or evidence reconciliation. This decision complements custom effective documents or evidence reconciliation. This decision complements
ADRs 0004 and 0005; the [adoption roadmap](../roadmap/commandkit-adoption.md) ADRs 0004 and 0005; the completed
records the implementation work. [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 The CLI exposes Promptkit's captured framework configuration inspection. Its
`show` and `explain` reports use Promptkit's native redaction for classified `show` and `explain` reports use Promptkit's native redaction for classified

View File

@@ -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

View File

@@ -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
View 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.

View File

@@ -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

View File

@@ -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

View File

@@ -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.

View File

@@ -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.

View File

@@ -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.

View File

@@ -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.