Files
scriptorium/docs/roadmap/implementation.md

39 KiB
Raw Blame History

CommandKit Adoption Implementation Plan

Purpose And Execution

Implement the target in the CommandKit adoption roadmap. This plan owns the implementation steps and concrete adapter choices; the roadmap owns product intent and target behavior. The migration notepad records the discussion. ADR 0006, ADR 0005, and ADR 0004 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. Read the applicable agent, architecture, testing, documentation, and OSS policies. Use the release policy 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 and CLI contract. 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.
Repeated --promptkit-source PATH Replace the complete promptkit_sources list during ConfigKit loading with the selected files/directories in occurrence order, as a native override. Retain the useful existing file/directory classification, without comma splitting.
--schema-dir Presence-aware override of application schema_dir.
--addr, --artifact-root, --max-request-bytes, --max-artifact-bytes, --max-response-bytes Presence-aware application server overrides; available on serve and application-scope configuration inspection.
config ... --set POINTER=JSON Ordered native override records for app; append after named application-selector overrides so native assignments are authoritative when both address the same value. Enable the feature only on app.
config diff --against-* Independent right-side selections and corresponding application-selector overrides, initialized independently rather than inherited from the left.
--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.

Framework selectors (promptkit-source, schema-dir) apply to both config scopes and to the native PromptKit family. Server selectors apply to the app scope only. Provide each config selector with its matching AgainstName, such as against-promptkit-source, against-schema-dir, or against-addr. run accepts the framework selectors, request controls, and delivery controls; it does not need server-only flags. serve accepts framework and server selectors, not generation request controls. The configured transient_retries value remains an engine default; the native execution flag overrides a request.

ConfigKit remains responsible for loading and all precedence, resolution, and inspection semantics. The override ordering above selects library inputs; it does not authorize post-load merging. Keep cwd-relative application path values, the existing discovery locations, and source-relative PromptKit resources.

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

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

Primary files: internal/config/{load,document,settings}.go, their tests, and CLI application-loading/source-selector 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 the existing ordered SearchConfig, imports remain enabled, and 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 application selectors into correctly labeled ConfigKit overrides, then append native Selection.Overrides as specified above. Keep source-list order and replacement. Use ordinary OS classification for explicitly supplied source paths; do not load framework definitions during application inspection. 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. Strict ConfigKit decoding handles the retired field; add no compatibility mapping.
  5. Retain shared engine construction from resolved settings: one ordered underlay per app selector, import-enabled file inputs, directory expansion through promptkit.DirectoryInputs, no implicit main, existing schema base and engine retry setting, and the default upstream bundle. Do not change collection traversal, peer composition, or whole-record replacement. DirectoryInputs retains explicit directory-selector support; collection discovery continues through the file source's ConfigKit import globs for collection.yml and collection.yaml.
  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, a supplied zero or empty app override, native --set precedence, ordered source replacement, normalized values and their evidence, and removal of render_format. Reuse existing import/search/source tests; do not reproduce ConfigKit's exhaustive composition matrix.

Stage 3: Install Native Configuration Scopes And Independent Comparison

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 selectors with their scopes and independent AgainstName bindings from the mapping above. Use fresh NewInput results, not shared pointers. 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/selectors, and diff-check status 3. Verify app overrides are available and framework overrides are not emulated.

Stage 4: Install Native PromptKit Resources, Requirements, And Preview

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

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 app config/overlay/framework-selector bindings. 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

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

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

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. Keep the useful source-to-underlay wiring in its new CLI home, not a resurrected 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 Removed render default; native overlay-name selection; application overrides and loader authority; app/framework scopes and native comparison. Preserve collection/source/default semantics.
    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; --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 remove the retired render default. 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

  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:

    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.

There are no unresolved product questions. The optional upstream selected-format accessor is not a migration dependency or completion gate.