base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Align reporting contracts and documentation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 05:06:47 +00:00
parent 1289868ed0
commit d14fa366f5
17 changed files with 160 additions and 169 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/cli.md
View File

@@ -114,7 +114,7 @@ and usage guidance go to `Streams.Err`.
The shared `--format` flag selects `text`, `yaml`, or `json` for reports
submitted through the core reporter. When omitted, a report's text template
selects text; otherwise scalar values and nonempty string lists use text, while
structured values and empty collections use YAML. Explicit text without a
structured values, empty collections, and null use YAML. Explicit text without a
template uses YAML for structured values. Invalid or empty format values are
usage errors. Raw output, help, completion, and diagnostics are not encoded as
reports.
@@ -537,7 +537,7 @@ separate evidence and does not replace a nonzero difference outcome.
For ConfigKit-backed scopes, ConfigKit compares frozen effective typed values
after defaults and resolution; source or provenance differences alone do not
create a change. PromptKit delegates its native comparison to ConfigKit. The
report contains `additions`, `changes`, and `deletions`. Additions and changes
concise report contains `additions`, `changes`, and `deletions`. Additions and changes
preserve semantic paths and contain right-side values provided by the native
comparison. Deletions contain canonical JSON
Pointer paths. Explicit null is a value; it is not a deletion. Changed sequences
@@ -545,7 +545,7 @@ and native structural replacement regions stay atomic.
ConfigKit pairs sensitivity across both loads. A concealed change can therefore
appear even when its two safe snapshots are equal. For those ConfigKit-backed
comparisons, the report omits separate redaction and hidden-change metadata: a
comparisons, the concise report omits separate redaction and hidden-change metadata: a
reported masked region changed, but that does not mean every member inside it
changed. Marker-looking public strings stay ordinary strings. An empty
comparison succeeds with this shape:
@@ -561,7 +561,7 @@ automatically applicable patch. Exceptional whole-root empty/null transitions
can be ambiguous because the report has no root envelope; ordinary field-level
null values and deletions retain their distinction.
Successful comparisons return status `0`, including empty results.
Without `--check`, successful comparisons return status `0`, including empty results.
Unsupported scopes and format errors are usage errors; input checks retain the
existing usage/operational classification. Load and native comparison failures
are operational and preserve supported error identity.
@@ -804,7 +804,7 @@ configuration and credential checks. It does not make a model call or retain a
prepared execution snapshot. A successful report describes this preparation
invocation; it does not certify provider acceptance or guarantee later
execution. See PromptKit's
[`Engine.ValidateRequest` API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/engine.go).
[`Engine.ValidateRequest` API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/engine.go).
Builder, engine-loading, and native validation errors use the operational path
(status `1`) with supported error identity and acquired diagnostics retained.
@@ -867,7 +867,7 @@ identities. YAML examples follow:
A catalog result is an inventory, not a readiness check or execution result.
The owning provider controls membership and order. Namespace filters are passed
to PromptKit without local membership interpretation. See the
[PromptKit v0.18.0 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/consumers/pkg-promptkit.md)
[PromptKit v0.20.0 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/consumers/pkg-promptkit.md)
for native resource and selection definitions.
### PromptKit smoke testing
@@ -1016,9 +1016,9 @@ operation causes. Syntax, operand, unsupported format, and conflicting
namespace selection are usage status `2`.
Native configuration, selection, and diagnostic meanings remain owned by
PromptKit. See the [v0.18.0 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/consumers/pkg-promptkit.md),
[smoke API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/smoke_diagnostics.go),
and [engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/engine.go).
PromptKit. See the [v0.20.0 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/consumers/pkg-promptkit.md),
[smoke API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/smoke_diagnostics.go),
and [engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/engine.go).
## Outcome status