diff --git a/docs/roadmap/commandkit-adoption.md b/docs/roadmap/commandkit-adoption.md index 45867c1..8241ff1 100644 --- a/docs/roadmap/commandkit-adoption.md +++ b/docs/roadmap/commandkit-adoption.md @@ -61,12 +61,10 @@ v0.23.2 minimum does not require a downgrade. Supported public APIs and released dependencies remain subject to the existing [architecture policy](../policy/architecture.md). -One approved upstream addition is needed: a released selected-format accessor. -CommandKit v0.7.0 provides a writer-level renderer but no public access to the -invocation's selected format. The accessor enables formatted application-owned -output files, including in quiet mode, without duplicating reporting-flag -parsing. The implementation plan tracks adoption of its released API; the -agreed file-output contract remains the target. +No selected-format accessor is required for this migration. The native +invocation reporter handles the main result on stdout; the existing writer API +handles the separate report using fixed JSON. The upstream accessor proposal +remains optional API work, independent of Scriptorium's adoption. ## Target End State @@ -210,17 +208,21 @@ remains upstream-owned. There is no Scriptorium result envelope. | Selection | Behavior | | --- | --- | -| No destination flag | Main result goes to stdout using the selected format. | -| `--output PATH` | Main result goes to that file, without duplicate stdout output. | +| Main result | Goes through the native invocation reporter to stdout using the selected format. | | `--format text` or default | Main result contains only the artifact. | | `--format json` or `--format yaml` | Main result contains the native result and metadata. | | `--report PATH` | Additionally write the native result as JSON through CommandKit's renderer, independently of the main format and destination. | -Filename extensions do not select formats. The separate report includes the -native result's content as well as metadata; it replaces the CLI's old +There is no `--output` or legacy `--out` flag. Callers save the main result by +redirecting stdout in a shell or supplying a file as the subprocess stdout +destination. Diagnostics remain on stderr. Callers wanting main output omit +`--quiet`, including when stdout is redirected. Filename extensions do not +select formats. The separate report includes the native result's content as +well as metadata; it replaces the CLI's old observer-derived metadata projection. A caller wanting an artifact file plus -metadata can select separate output and report paths. The caller manages paths -and retention; there is no automatic reporting directory or report collection. +metadata redirects stdout and selects a separate `--report` path. The caller +manages redirected destinations and retention; there is no automatic reporting +directory or report collection. Native result reporting is available when PromptKit returns a result. Operational errors return nonzero status and native failure diagnostics, without @@ -231,10 +233,10 @@ invocation-error envelope is part of this migration. Adopt CommandKit's quiet and verbosity semantics, including rendering and presentation failures. Console results use the invocation reporter; diagnostics -use its diagnostic channel. Explicit `--output` and `--report` writes are -application effects rendered through the writer API and still occur in quiet -mode. Quiet does not cancel generation; without requested files it suppresses -ordinary result output while failure explanations remain visible. Move any +use its diagnostic channel. An explicit `--report` write is an application +effect rendered as JSON through the writer API and still occurs in quiet mode. +Quiet does not cancel generation; it suppresses the main result even when +stdout is redirected, while failure explanations remain visible. Move any retained generation summary into an appropriate native message category. Map typed upstream failures and configuration diagnostics into native outcomes, @@ -246,11 +248,13 @@ native presentation-failure behavior where applicable, including an already nonzero domain outcome. Requested file errors must not disappear merely because they occur outside the invocation reporter. -Use ordinary file operations: replace files without creating parents, reject -output/report destinations known to name the same file before execution, -attempt the main output followed by the report, and attempt the report even if -main delivery fails. This adds no rollback, transactional delivery, or stronger -filesystem protection. Already delivered output may remain after failure. +For `--report`, use ordinary file replacement without creating parents. Attempt +the main output followed by the report, and attempt the report even if main +delivery fails. Open the report only when a native result exists. Redirection +and its file-creation or truncation behavior belong to the caller. Scriptorium +does not manage the main output file or check it against the report path. This +adds no rollback or transactional delivery; written bytes may remain after +failure. Wire signal cancellation through the invocation context. Keep the application whole-operation budget separate from the native per-attempt timeout binding. @@ -264,8 +268,7 @@ Remove `render`, its compatibility aliases, `defaults.render_format`, and unused prepared-output formatters. Native prepared preview uses its upstream report, default/text YAML presentation, standard formats, request flags, diagnostics, and outcomes. It does not call a model. Consumers save preview -output through stdout capture or redirection; generation's `--output` does not -extend the native inspection families. +output through stdout capture or redirection, as they do for generation. Adopt native inspection reports, including captured prompt messages and rendered prepared content, without recreating old summary projections. Native schemas @@ -292,8 +295,9 @@ documentation and examples describe the shipped interface. In particular: preparation, discovery, and inspection of multiple independently maintained collections. Their upstream lifecycle differences remain visible. - Generation defaults to the artifact alone; structured output and separate - reports expose the native result. Requested files remain independent of - console quiet mode, with useful failure outcomes and nontransactional delivery. + reports expose the native result. Main output uses stdout and native quiet + semantics; the optional JSON report file is written independently of quiet, + with useful failure outcomes and nontransactional delivery. - Narratio's linked acceptance scenarios are supported, including useful partial discovery and discovery before generated artifacts exist. - Native help, aliases, completion, and explicit smoke testing are available. @@ -304,13 +308,13 @@ documentation and examples describe the shipped interface. In particular: - Canonical contracts, examples, dependency attribution, and migration guidance reflect the cutover. The CLI migration includes positional prompt selection, command replacements, literal versus file inputs, repeated mappings, overlay - selection, native endpoint/timeout controls, content-bearing reports, report - availability, quiet behavior, and changed exit statuses. + selection, native endpoint/timeout controls, stdout redirection in place of + output-file flags, content-bearing reports, report availability, quiet + behavior, and changed exit statuses. The [implementation plan](implementation.md) owns task sequencing, concrete adapter mappings, verification steps, and sprint status. There are no unresolved -product decisions; the approved upstream selected-format accessor remains an -external release prerequisite. +product decisions or selected-format accessor release prerequisite. The [release policy](../policy/release.md#versioning-and-compatibility) governs the eventual breaking release version. This migration does not itself select diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index 566baf9..7c74bf8 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -128,16 +128,16 @@ format to compensate for the absence of a native result. ### Output destinations and verbosity -Decision recorded 2026-11-19: use `--output PATH` for the main result's file -destination. Without it, the main result goes to stdout. With it, the selected -representation goes to the file without duplicate stdout output. Use the -spelling `--output`, with no legacy `--out` compatibility alias. +Decision revised 2026-11-19: remove the previously selected `--output` flag. +The main result uses the native invocation reporter and stdout. Callers save it +through shell redirection or a subprocess stdout destination; diagnostics remain +on stderr. Do not retain the old `--out` flag. -`--format` selects the representation independently of the destination: +`--format` selects the stdout representation independently of redirection: default/text emits the raw artifact, while JSON/YAML emits the native result with metadata. The filename does not select the format. `--report PATH` remains an additional native JSON report, so callers can save the raw artifact and its -report to separate files. +report to separate files by redirecting stdout and supplying `--report`. Adopt CommandKit's upstream verbosity and `--quiet` semantics fully, including mode selection, message visibility, rendering, and presentation failures. Do @@ -145,13 +145,12 @@ not add Scriptorium-specific exceptions to normal command-output suppression. Quiet mode does not cancel generation, and failure explanations remain visible through the native diagnostic channel. -Explicitly requested `--output` and `--report` writes are application-owned file -operations and still occur in quiet mode. Render those files through CommandKit's -writer API; the invocation reporter governs console output. This follows the -upstream distinction between reporting visibility and application effects. -With quiet mode and no requested files, generation still runs while ordinary -result output is suppressed. The [upstream reporting contract][upstream-cli] -owns the shared verbosity rules. +An explicit `--report` write remains an application-owned effect in quiet mode, +using the existing writer API with fixed JSON. Quiet suppresses the main result +even when stdout is redirected; callers wanting that result omit quiet. No +selected-format accessor is needed, so the upstream proposal is no longer a +migration prerequisite. The [upstream reporting contract][upstream-cli] owns the +shared verbosity rules. ### Prepared-request preview @@ -170,8 +169,7 @@ request construction with generation so previews describe the corresponding execution request. PromptKit continues to own preparation semantics. Use the native result stream for preview output; consumers can capture or -redirect stdout to save it. The generation command's `--output` decision does -not itself extend the native inspection commands. File-output convenience does +redirect stdout to save it, as with generation. File-output convenience does not justify retaining a separate preview command. Update maintained examples and release migration guidance to use `promptkit show prepared`. @@ -245,7 +243,7 @@ families. The CLI migration does not redesign the HTTP API. Reuse ckprompt's applicable resource, input, and execution flag bindings. Preserve native parsing, explicit-value presence, repeated mapping semantics, and PromptKit's interpretation of request values. Keep application-specific -configuration/source selection, `--output`, `--report`, server options, and the +configuration/source selection, `--report`, server options, and the whole-operation deadline separate from framework request controls. Enable upstream convenience aliases consistently on applicable commands, @@ -308,10 +306,11 @@ units, separately from the standard per-attempt timeout flag. ### File delivery -Specify ordinary path handling, overwriting, parent-directory behavior, -destination collisions, and delivery ordering for `--output` and `--report`. -Describe partial delivery consistently with native outcome reporting and the -agreed upstream result-availability boundary. +The roadmap and implementation plan specify ordinary report-file handling and +delivery ordering relative to stdout. The caller owns redirected destinations; +Scriptorium does not infer them or check for collisions with the report path. +Partial delivery follows native outcomes and the agreed result-availability +boundary. ### Adoption and verification diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index b0bbfe0..50b9d73 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -32,7 +32,7 @@ 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 +## Released Dependencies And Selected Integration The reviewed public APIs are documented at CommandKit revision `d330d7637f2e7507eca931a899397222c82bc892` in its @@ -45,27 +45,16 @@ baseline is: | `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. +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. -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. +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, FormatJSON)` API. +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 @@ -110,12 +99,12 @@ the existing discovery locations, and source-relative PromptKit resources. | --- | --- | | 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. | +| 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. | -| 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. | +| 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 @@ -128,40 +117,42 @@ Its reusable text template emits `Artifact.Body` as bytes represented as a strin 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. +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`. -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. +`--report PATH` additionally renders the same native result as fixed JSON via +`commandkit.RenderReport`, regardless of the main format or stdout destination. +This application-owned file write still occurs in quiet mode. Omitting the flag +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. 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. +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 released selected-format accessor prerequisite above and select - the minimal compatible released module combination. Record the actual +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 addition supplies a + 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 @@ -358,7 +349,7 @@ helpers in `internal/adapter/cli`, and run integration tests. 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. + the separate JSON report without changing the result shape. **Evidence:** real-engine/controlled-provider tests exercise the assembled positional command, preferred aliases, literal/file precedence, comma-containing @@ -368,41 +359,41 @@ 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 +## Stage 6: Add Separate 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. +1. Add `--report` as a presence-aware application file flag with path completion. + Reject an explicitly empty path before executing the model. Do not create + files during validation or add a main-output destination flag. 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 + Main stdout uses `Invocation.Reporter().Report`; the separate report uses + `RenderReport(..., FormatJSON)`. 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 files. + 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; explicit + 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, 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. +**Evidence:** cover default/text raw bytes and JSON/YAML through stdout, including +a subprocess whose stdout is redirected to a file. Check separate JSON report +equivalence to inline native JSON and independence from the main format. Quiet +suppresses main output, including redirected stdout, while an explicitly requested +report is still written. Test empty report paths, 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 @@ -465,7 +456,7 @@ version output. Test-local fallback deadlines prevent regressions from hanging. | 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/cli.md` | New command tree, applicable flags/aliases, native selection/reporting, stdout redirection and separate report-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. | @@ -477,8 +468,9 @@ version output. Test-local fallback deadlines prevent regressions from hanging. 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. + stdout redirection in place of output-file flags; separate JSON reports, + native formats, 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 @@ -516,10 +508,10 @@ current documentation links resolve. Migration examples match the built CLI. 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. +4. Review the output/outcome matrix across stdout, caller redirection, report + 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 @@ -544,12 +536,10 @@ current documentation links resolve. Migration examples match the built CLI. 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. + not mark the migration complete while 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. +There are no unresolved product questions. The optional upstream selected-format +accessor is not a migration dependency or completion gate. [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