817 lines
54 KiB
Markdown
817 lines
54 KiB
Markdown
# 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
|