Use stdout redirection for main generation output

This commit is contained in:
2026-11-20 02:16:44 +00:00
parent 99b0ebfc03
commit fbe7dd56e3
3 changed files with 120 additions and 127 deletions

View File

@@ -61,12 +61,10 @@ v0.23.2 minimum does not require a downgrade. Supported public APIs and released
dependencies remain subject to the existing dependencies remain subject to the existing
[architecture policy](../policy/architecture.md). [architecture policy](../policy/architecture.md).
One approved upstream addition is needed: a released selected-format accessor. No selected-format accessor is required for this migration. The native
CommandKit v0.7.0 provides a writer-level renderer but no public access to the invocation reporter handles the main result on stdout; the existing writer API
invocation's selected format. The accessor enables formatted application-owned handles the separate report using fixed JSON. The upstream accessor proposal
output files, including in quiet mode, without duplicating reporting-flag remains optional API work, independent of Scriptorium's adoption.
parsing. The implementation plan tracks adoption of its released API; the
agreed file-output contract remains the target.
## Target End State ## Target End State
@@ -210,17 +208,21 @@ remains upstream-owned. There is no Scriptorium result envelope.
| Selection | Behavior | | Selection | Behavior |
| --- | --- | | --- | --- |
| No destination flag | Main result goes to stdout using the selected format. | | Main result | Goes through the native invocation reporter to stdout using the selected format. |
| `--output PATH` | Main result goes to that file, without duplicate stdout output. |
| `--format text` or default | Main result contains only the artifact. | | `--format text` or default | Main result contains only the artifact. |
| `--format json` or `--format yaml` | Main result contains the native result and metadata. | | `--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. | | `--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 There is no `--output` or legacy `--out` flag. Callers save the main result by
native result's content as well as metadata; it replaces the CLI's old 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 observer-derived metadata projection. A caller wanting an artifact file plus
metadata can select separate output and report paths. The caller manages paths metadata redirects stdout and selects a separate `--report` path. The caller
and retention; there is no automatic reporting directory or report collection. manages redirected destinations and retention; there is no automatic reporting
directory or report collection.
Native result reporting is available when PromptKit returns a result. Native result reporting is available when PromptKit returns a result.
Operational errors return nonzero status and native failure diagnostics, without 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 Adopt CommandKit's quiet and verbosity semantics, including rendering and
presentation failures. Console results use the invocation reporter; diagnostics presentation failures. Console results use the invocation reporter; diagnostics
use its diagnostic channel. Explicit `--output` and `--report` writes are use its diagnostic channel. An explicit `--report` write is an application
application effects rendered through the writer API and still occur in quiet effect rendered as JSON through the writer API and still occurs in quiet mode.
mode. Quiet does not cancel generation; without requested files it suppresses Quiet does not cancel generation; it suppresses the main result even when
ordinary result output while failure explanations remain visible. Move any stdout is redirected, while failure explanations remain visible. Move any
retained generation summary into an appropriate native message category. retained generation summary into an appropriate native message category.
Map typed upstream failures and configuration diagnostics into native outcomes, 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 nonzero domain outcome. Requested file errors must not disappear merely because
they occur outside the invocation reporter. they occur outside the invocation reporter.
Use ordinary file operations: replace files without creating parents, reject For `--report`, use ordinary file replacement without creating parents. Attempt
output/report destinations known to name the same file before execution, the main output followed by the report, and attempt the report even if main
attempt the main output followed by the report, and attempt the report even if delivery fails. Open the report only when a native result exists. Redirection
main delivery fails. This adds no rollback, transactional delivery, or stronger and its file-creation or truncation behavior belong to the caller. Scriptorium
filesystem protection. Already delivered output may remain after failure. 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 Wire signal cancellation through the invocation context. Keep the application
whole-operation budget separate from the native per-attempt timeout binding. 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 unused prepared-output formatters. Native prepared preview uses its upstream
report, default/text YAML presentation, standard formats, request flags, report, default/text YAML presentation, standard formats, request flags,
diagnostics, and outcomes. It does not call a model. Consumers save preview diagnostics, and outcomes. It does not call a model. Consumers save preview
output through stdout capture or redirection; generation's `--output` does not output through stdout capture or redirection, as they do for generation.
extend the native inspection families.
Adopt native inspection reports, including captured prompt messages and rendered Adopt native inspection reports, including captured prompt messages and rendered
prepared content, without recreating old summary projections. Native schemas 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 preparation, discovery, and inspection of multiple independently maintained
collections. Their upstream lifecycle differences remain visible. collections. Their upstream lifecycle differences remain visible.
- Generation defaults to the artifact alone; structured output and separate - Generation defaults to the artifact alone; structured output and separate
reports expose the native result. Requested files remain independent of reports expose the native result. Main output uses stdout and native quiet
console quiet mode, with useful failure outcomes and nontransactional delivery. 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 - Narratio's linked acceptance scenarios are supported, including useful partial
discovery and discovery before generated artifacts exist. discovery and discovery before generated artifacts exist.
- Native help, aliases, completion, and explicit smoke testing are available. - 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 - Canonical contracts, examples, dependency attribution, and migration guidance
reflect the cutover. The CLI migration includes positional prompt selection, reflect the cutover. The CLI migration includes positional prompt selection,
command replacements, literal versus file inputs, repeated mappings, overlay command replacements, literal versus file inputs, repeated mappings, overlay
selection, native endpoint/timeout controls, content-bearing reports, report selection, native endpoint/timeout controls, stdout redirection in place of
availability, quiet behavior, and changed exit statuses. output-file flags, content-bearing reports, report availability, quiet
behavior, and changed exit statuses.
The [implementation plan](implementation.md) owns task sequencing, concrete The [implementation plan](implementation.md) owns task sequencing, concrete
adapter mappings, verification steps, and sprint status. There are no unresolved adapter mappings, verification steps, and sprint status. There are no unresolved
product decisions; the approved upstream selected-format accessor remains an product decisions or selected-format accessor release prerequisite.
external release prerequisite.
The [release policy](../policy/release.md#versioning-and-compatibility) governs The [release policy](../policy/release.md#versioning-and-compatibility) governs
the eventual breaking release version. This migration does not itself select the eventual breaking release version. This migration does not itself select

View File

@@ -128,16 +128,16 @@ format to compensate for the absence of a native result.
### Output destinations and verbosity ### Output destinations and verbosity
Decision recorded 2026-11-19: use `--output PATH` for the main result's file Decision revised 2026-11-19: remove the previously selected `--output` flag.
destination. Without it, the main result goes to stdout. With it, the selected The main result uses the native invocation reporter and stdout. Callers save it
representation goes to the file without duplicate stdout output. Use the through shell redirection or a subprocess stdout destination; diagnostics remain
spelling `--output`, with no legacy `--out` compatibility alias. 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 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 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 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 Adopt CommandKit's upstream verbosity and `--quiet` semantics fully, including
mode selection, message visibility, rendering, and presentation failures. Do 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 Quiet mode does not cancel generation, and failure explanations remain visible
through the native diagnostic channel. through the native diagnostic channel.
Explicitly requested `--output` and `--report` writes are application-owned file An explicit `--report` write remains an application-owned effect in quiet mode,
operations and still occur in quiet mode. Render those files through CommandKit's using the existing writer API with fixed JSON. Quiet suppresses the main result
writer API; the invocation reporter governs console output. This follows the even when stdout is redirected; callers wanting that result omit quiet. No
upstream distinction between reporting visibility and application effects. selected-format accessor is needed, so the upstream proposal is no longer a
With quiet mode and no requested files, generation still runs while ordinary migration prerequisite. The [upstream reporting contract][upstream-cli] owns the
result output is suppressed. The [upstream reporting contract][upstream-cli] shared verbosity rules.
owns the shared verbosity rules.
### Prepared-request preview ### Prepared-request preview
@@ -170,8 +169,7 @@ request construction with generation so previews describe the corresponding
execution request. PromptKit continues to own preparation semantics. execution request. PromptKit continues to own preparation semantics.
Use the native result stream for preview output; consumers can capture or Use the native result stream for preview output; consumers can capture or
redirect stdout to save it. The generation command's `--output` decision does redirect stdout to save it, as with generation. File-output convenience does
not itself extend the native inspection commands. File-output convenience does
not justify retaining a separate preview command. Update maintained examples not justify retaining a separate preview command. Update maintained examples
and release migration guidance to use `promptkit show prepared`. 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. Reuse ckprompt's applicable resource, input, and execution flag bindings.
Preserve native parsing, explicit-value presence, repeated mapping semantics, Preserve native parsing, explicit-value presence, repeated mapping semantics,
and PromptKit's interpretation of request values. Keep application-specific 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. whole-operation deadline separate from framework request controls.
Enable upstream convenience aliases consistently on applicable commands, Enable upstream convenience aliases consistently on applicable commands,
@@ -308,10 +306,11 @@ units, separately from the standard per-attempt timeout flag.
### File delivery ### File delivery
Specify ordinary path handling, overwriting, parent-directory behavior, The roadmap and implementation plan specify ordinary report-file handling and
destination collisions, and delivery ordering for `--output` and `--report`. delivery ordering relative to stdout. The caller owns redirected destinations;
Describe partial delivery consistently with native outcome reporting and the Scriptorium does not infer them or check for collisions with the report path.
agreed upstream result-availability boundary. Partial delivery follows native outcomes and the agreed result-availability
boundary.
### Adoption and verification ### Adoption and verification

View File

@@ -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`, `cmd/scriptorium`, `internal/adapter/cli`, `internal/config`, `internal/format`,
`internal/report`, and the unchanged `internal/adapter/http`. `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 The reviewed public APIs are documented at CommandKit revision
`d330d7637f2e7507eca931a899397222c82bc892` in its `d330d7637f2e7507eca931a899397222c82bc892` in its
@@ -45,27 +45,16 @@ baseline is:
| `go.maximumdirect.net/ckconfig` | v0.9.0 | `9962368f0c1ea1f6ad010638e94621091105d745` | | `go.maximumdirect.net/ckconfig` | v0.9.0 | `9962368f0c1ea1f6ad010638e94621091105d745` |
| `go.maximumdirect.net/ckprompt` | v0.10.0 | `c9a56e1b15f2169881a91fca4e1f4a1c475e057a` | | `go.maximumdirect.net/ckprompt` | v0.10.0 | `c9a56e1b15f2169881a91fca4e1f4a1c475e057a` |
There is one approved external prerequisite. CommandKit v0.7.0 has the public Use the reviewed released combination and verify it in Stage 1. Preserve
`RenderReport(writer, report, format)` API but does not expose the invocation's ConfigKit v1.2.1 and PromptKit v0.23.3; ckprompt's PromptKit v0.23.2 minimum is
selected format. Its invocation reporter suppresses console writes in quiet not a reason to downgrade. Raise any demonstrated compatibility problem before
mode. Consequently that release alone cannot implement the agreed formatted expanding this sprint into another framework upgrade.
`--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 No selected-format accessor is required. Main results go through the native
addition; adopt corresponding released integration updates only if needed for invocation reporter to stdout, with caller-controlled redirection. The separate
that capability. Preserve ConfigKit v1.2.1 and PromptKit v0.23.3 unless that `--report` file uses the existing `RenderReport(writer, report, FormatJSON)` API.
necessary released combination requires a separately reviewed change. In The upstream accessor proposal is optional and does not block any stage. Do not
particular, ckprompt's PromptKit v0.23.2 minimum is not a reason to downgrade. add a second reporting-flag parser or private-API workaround.
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 ## 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 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. | | 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. | | 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. | | 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. | | 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. | | 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 Use `errors.Is`/`errors.As`, not error-text matching. Apply cancellation and
typed operation-timeout handling before configuration classification. Do not 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 with no added newline, header, escaping, or summary. Native JSON/YAML serialization
remains upstream-owned, including byte representation and native metadata. remains upstream-owned, including byte representation and native metadata.
Without `--output`, submit the report through the invocation reporter. With Submit the main report through `Invocation.Reporter().Report`. There is no
`--output PATH`, render through `commandkit.RenderReport` to that file using `--output` or legacy `--out` flag. Callers save stdout using shell redirection or
the upstream selected-format accessor; do not also submit a console result. their subprocess API; Scriptorium keeps diagnostics on stderr. Native quiet
`--report PATH` additionally renders the same native result as JSON, regardless suppresses the main result even when stdout is redirected. Consumers wanting
of main format or destination. Explicit files are application effects and are that result omit `--quiet`.
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, `--report PATH` additionally renders the same native result as fixed JSON via
subject to umask), preserve normal OS behavior for existing files, and handle `commandkit.RenderReport`, regardless of the main format or stdout destination.
render/write/close errors. Do not create parent directories. Explicit empty This application-owned file write still occurs in quiet mode. Omitting the flag
destination values are usage errors; `-` is an ordinary filename. Before creates no separate report. Use ordinary create/truncate operations (mode 0644
generation, reject output/report paths known to identify the same file using for newly created files, subject to umask), preserve normal OS behavior for
cleaned absolute path equality and `os.SameFile` for existing destinations. existing files, and handle render/write/close errors. Do not create parent
This is a best-effort collision check, not a filesystem-race guarantee. 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 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 report, even if the first attempt fails. Open the report only after a result
before a result exists. No native result means no replacement report or output exists; a resultless failure leaves an existing report untouched. This does not
file; an existing destination can remain from a previous invocation. Delivery govern a caller's redirection: a shell may create or truncate its destination
is nontransactional: written bytes remain after failure. No rollback, atomic before Scriptorium runs. Delivery is nontransactional; written bytes remain
replacement, symlink sandbox, or additional filesystem hardening is requested. after failure. No rollback, atomic replacement, symlink sandbox, or additional
filesystem hardening is requested.
## Stage 1: Select Released Dependencies And Establish Command Composition ## Stage 1: Select Released Dependencies And Establish Command Composition
**Primary files:** `go.mod`, `go.sum`, `internal/adapter/cli` composition, **Primary files:** `go.mod`, `go.sum`, `internal/adapter/cli` composition,
`docs/oss/attribution.md`, and applicable `docs/oss/licenses/` texts. `docs/oss/attribution.md`, and applicable `docs/oss/licenses/` texts.
1. Verify the released selected-format accessor prerequisite above and select 1. Verify the reviewed released module combination above. Record the actual
the minimal compatible released module combination. Record the actual
versions and complete source commits in this plan's implementation status versions and complete source commits in this plan's implementation status
and attribution entries as appropriate; use released modules, not sibling and attribution entries as appropriate; use released modules, not sibling
checkouts, workspaces, vendoring, or replacements. checkouts, workspaces, vendoring, or replacements.
2. Add CommandKit, ckconfig, and ckprompt dependencies. Keep the existing Go 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. concrete contrary requirement; raise such an expansion rather than guessing.
Verify selected PromptKit/ConfigKit versions and tidy the module metadata. Verify selected PromptKit/ConfigKit versions and tidy the module metadata.
3. Create the CLI composition entry point in `internal/adapter/cli`. Accept a 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 7. Build the native result report/text template and submit stdout results
through the invocation reporter. Keep any retained generation summary as a through the invocation reporter. Keep any retained generation summary as a
native Info message, normally hidden at ordinary verbosity. Stage 6 adds 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 **Evidence:** real-engine/controlled-provider tests exercise the assembled
positional command, preferred aliases, literal/file precedence, comma-containing 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 failure/status 1. Include a small typed-error mapping table rather than parsing
error prose. Use native config classification for representative load failures. 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. **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 1. Add `--report` as a presence-aware application file flag with path completion.
path completion. Validate empty values and known destination collisions Reject an explicitly empty path before executing the model. Do not create
before executing the model. Do not create files during validation. files during validation or add a main-output destination flag.
2. Implement the settled delivery rules using the same report as Stage 5. 2. Implement the settled delivery rules using the same report as Stage 5.
Main stdout uses `Invocation.Reporter().Report`; main files use Main stdout uses `Invocation.Reporter().Report`; the separate report uses
`RenderReport` and the upstream selected format; separate reports use `RenderReport(..., FormatJSON)`. The invocation reporter owns main format
`RenderReport(..., FormatJSON)`. The default selected format must continue selection, including automatic artifact-template output. No selected-format
to use the artifact-only text template. Extensions never select formats. accessor is needed. Extensions never select formats.
3. Keep explicit file effects independent of console quiet selection. Do not 3. Keep the report file effect independent of console quiet selection. Do not
temporarily change reporting mode, rerun `App.Execute`, capture stdout and 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. Keep file rendering outside reporter render callbacks to avoid reentrancy.
4. Attempt main delivery and then the requested report even when the first 4. Attempt main delivery and then the requested report even when the first
fails, retaining every relevant delivery error. Include useful failure fails, retaining every relevant delivery error. Include useful failure
explanations and preserve the selected nonzero domain outcome. Console 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. 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. 5. Remove the CLI observer/report collector wiring and old report-file format.
Leave `internal/report` and HTTP report attachment intact. Only a returned Leave `internal/report` and HTTP report attachment intact. Only a returned
native run result is eligible for the new CLI report file. native run result is eligible for the new CLI report file.
**Evidence:** cover default/text raw bytes, JSON and YAML main files, JSON **Evidence:** cover default/text raw bytes and JSON/YAML through stdout, including
separate report equivalence to inline native JSON, no duplicate stdout, a subprocess whose stdout is redirected to a file. Check separate JSON report
format/extension independence, and quiet with/without requested files. Test equivalence to inline native JSON and independence from the main format. Quiet
empty paths, same cleaned path, existing same-file aliases, replacement without suppresses main output, including redirected stdout, while an explicitly requested
parent creation, first-delivery failure followed by report attempt, report report is still written. Test empty report paths, replacement without parent
failure after successful main delivery, and an unchanged existing report on a creation, stdout failure followed by report attempt, report failure after
resultless operational failure. Use temporary files and a small failing-writer successful main delivery, and an unchanged existing report on a resultless
seam for stdout/render failures. Confirm status 4 survives a delivery failure operational failure. Use temporary files and a small failing-writer seam for
while its explanation identifies the failure. No exhaustive filesystem matrix. 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 ## 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 | | 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/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/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/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 CLI/consumer overview. Cover positional prompt selection; `render` and
`inspect` replacements; file versus literal inputs; repeated mappings without `inspect` replacements; file versus literal inputs; repeated mappings without
comma splitting; `--overlay` names; endpoint and timeout spelling/units; comma splitting; `--overlay` names; endpoint and timeout spelling/units;
output/report destinations, native formats, and result availability; quiet stdout redirection in place of output-file flags; separate JSON reports,
behavior; status changes; and content-bearing native inspection/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, This prepares release migration information without selecting a version,
editing published notes, tagging, pushing, or adding release gates. Eventual editing published notes, tagging, pushing, or adding release gates. Eventual
release notes must summarize the breaking change and link the guide under 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 Help/version/scope discovery/static completion work without configuration or
provider availability. Confirm retired commands/flags are absent or rejected provider availability. Confirm retired commands/flags are absent or rejected
except where a spelling now intentionally has its native meaning (`--input`). except where a spelling now intentionally has its native meaning (`--input`).
4. Review the output/outcome matrix across stdout, requested files, quiet, 4. Review the output/outcome matrix across stdout, caller redirection, report
completed validation failure, operational failures, presentation errors, files, quiet, completed validation failure, operational failures, presentation
cancellation, and partial delivery. Verify reports are native values with errors, cancellation, and partial delivery. Verify reports are native values
no Scriptorium wrapper, and HTTP's distinct contract remains unchanged. with no Scriptorium wrapper, and HTTP's distinct contract remains unchanged.
5. Run the repository baseline on the selected toolchain: 5. Run the repository baseline on the selected toolchain:
```sh ```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 7. Record completion and the actual dependency/API selections after successful
verification. Commit the finished implementation units under the agent verification. Commit the finished implementation units under the agent
policy and report checks, commits, and any remaining work accurately. Do policy and report checks, commits, and any remaining work accurately. Do
not mark the migration complete while the approved upstream accessor or not mark the migration complete while required acceptance behavior is missing.
required acceptance behavior is missing.
There are no unresolved product questions. The selected-format accessor is an There are no unresolved product questions. The optional upstream selected-format
approved external release prerequisite, with its exact API/version to be accessor is not a migration dependency or completion gate.
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-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 [upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md