Files
scriptorium/docs/roadmap/implementation.md

556 lines
38 KiB
Markdown
Raw Normal View History

2026-11-20 01:07:52 +00:00
# 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`.
## Dependency Prerequisite 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` |
There is one approved external prerequisite. CommandKit v0.7.0 has the public
`RenderReport(writer, report, format)` API but does not expose the invocation's
selected format. Its invocation reporter suppresses console writes in quiet
mode. Consequently that release alone cannot implement the agreed formatted
`--output` behavior, including quiet-mode file delivery, through the intended
APIs. The user selected a **released upstream selected-format accessor** as the
solution. Adopt that capability before implementing Stage 6. Its final exported
name and release number are determined upstream, not invented here.
Keep ckconfig v0.9.0 and ckprompt v0.10.0 if they compose with the released core
addition; adopt corresponding released integration updates only if needed for
that capability. Preserve ConfigKit v1.2.1 and PromptKit v0.23.3 unless that
necessary released combination requires a separately reviewed change. In
particular, ckprompt's PromptKit v0.23.2 minimum is not a reason to downgrade.
Do not opportunistically expand this sprint into another framework upgrade.
Stage 1 confirms the actual release and API. If unavailable, record the external
dependency and leave the affected work incomplete pending its release. Do not
silently reduce the output contract, parse reporting flags again, use reflection
or private APIs, or commit a local module replacement. The upstream addition is
not an unresolved product choice and is not work to implement in this repository.
## 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, declaration-input, or destination-combination errors | 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. |
| Explicit file delivery failure | Operational 1 for an otherwise successful run. Preserve an already nonzero domain status 4 while adding the delivery explanation/cause. Attempt remaining requested delivery. |
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 one `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.
Without `--output`, submit the report through the invocation reporter. With
`--output PATH`, render through `commandkit.RenderReport` to that file using
the upstream selected-format accessor; do not also submit a console result.
`--report PATH` additionally renders the same native result as JSON, regardless
of main format or destination. Explicit files are application effects and are
written even in quiet mode. No separate report is created when the flag is absent.
Use ordinary create/truncate file 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. Explicit empty
destination values are usage errors; `-` is an ordinary filename. Before
generation, reject output/report paths known to identify the same file using
cleaned absolute path equality and `os.SameFile` for existing destinations.
This is a best-effort collision check, not a filesystem-race guarantee.
Once a result is available, attempt main delivery first, then the separate
report, even if the first attempt fails. Do not precreate or truncate files
before a result exists. No native result means no replacement report or output
file; an existing destination can remain from a previous invocation. 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 released selected-format accessor prerequisite above and select
the minimal compatible released module combination. 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 addition supplies 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.
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](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
**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
explicit destinations 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.
## Stage 6: Add Explicit Output And Native JSON Report Delivery
**Primary files:** CLI generation-delivery helpers and focused delivery tests.
Requires the released upstream selected-format accessor confirmed in Stage 1.
1. Add `--output` and `--report` as presence-aware application file flags with
path completion. Validate empty values and known destination collisions
before executing the model. Do not create files during validation.
2. Implement the settled delivery rules using the same report as Stage 5.
Main stdout uses `Invocation.Reporter().Report`; main files use
`RenderReport` and the upstream selected format; separate reports use
`RenderReport(..., FormatJSON)`. The default selected format must continue
to use the artifact-only text template. Extensions never select formats.
3. Keep explicit file effects 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 files.
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; explicit
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, JSON and YAML main files, JSON
separate report equivalence to inline native JSON, no duplicate stdout,
format/extension independence, and quiet with/without requested files. Test
empty paths, same cleaned path, existing same-file aliases, replacement without
parent creation, first-delivery 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, run destinations, file semantics, 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;
output/report destinations, native formats, and result availability; quiet
behavior; 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, requested files, 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 the approved upstream accessor or
required acceptance behavior is missing.
There are no unresolved product questions. The selected-format accessor is an
approved external release prerequisite, with its exact API/version to be
confirmed in Stage 1; it does not authorize a local workaround.
[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