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

Clarify comparison provider and delivery guarantees

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-12 00:15:04 +00:00
parent 98c9c3f00d
commit 251d3adeee
2 changed files with 30 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/cli.md
View File

@@ -232,15 +232,16 @@ serialized as `[]`.
### Compare configuration selections
`config diff` compares two independently loaded selections for one scope that
declares comparison. The default scope is `app`; `--scope all` is unsupported.
`config diff` prepares two selections for one scope that declares comparison
and invokes its comparison provider after input checks pass. The default scope
is `app`; `--scope all` is unsupported.
The PromptKit engine scope does not currently declare comparison, so selecting
`--scope promptkit` is a usage error.
`--config` and `--overlay` select the left side. `--against-config` and
`--against-overlay` independently override the right side. When a right-side
field is omitted, it inherits the corresponding left value and supplied state;
an explicit empty string overrides it and remains supplied. Equal selections are
allowed and both reached sides are loaded.
allowed; their equality alone does not cause CommandKit to skip the provider.
YAML is the only format and the default. Explicit `--format yaml` is accepted;
`text` and other formats are usage errors. For example:
@@ -279,13 +280,21 @@ null values and deletions retain their distinction.
Successful comparisons return status `0`, including concealed or 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. Comparison
diagnostics identify their left/right side and source legend. The adapter loads
left before right, retains left diagnostics if right loading fails, and gathers
both loads' diagnostics before native comparison. The complete report is
prepared before writing. Cancellation and preparation failures leave report
output empty; an output error or short write uses the existing incomplete-report
delivery outcome.
are operational and preserve supported error identity.
The bundled `FromConfigKit` and `AppCommand` adapters invoke the supplied loader
for each reached side, left before right, then call native comparison. They label
native diagnostics with their left/right side and source legend, retain left
diagnostics if right loading fails, and gather both loads' diagnostics before
native comparison. Custom pair providers own their loading and diagnostics;
application loaders and caches determine whether a loader call reads sources
again.
The complete report is prepared before writing. Report preparation failures and
cancellation observed before report delivery starts leave CommandKit's report
output empty. Once writing starts, CommandKit does not interrupt the supplied
writer or roll back delivered bytes. A write error or short write uses the
existing incomplete-report delivery outcome and can leave partial output.
## PromptKit definition inspection

13
docs/roadmap/remediation.md
View File

@@ -1,6 +1,6 @@
# Configuration comparison review remediation
Status: one finding complete; three open. This document tracks required
Status: two findings complete; two open. This document tracks required
follow-up work and its completion evidence.
## Review baseline and scope
@@ -73,7 +73,7 @@ benchmark, or performance gate was added.
## R-2: Scope CLI guarantees to the actual provider and delivery boundaries
**Status:** Open. **Priority:** Medium. **Category:** Inadvertently strengthened
**Status:** Complete. **Priority:** Medium. **Category:** Inadvertently strengthened
contracts / documentation accuracy.
**Evidence:** The [comparison CLI reference](../cli.md#compare-configuration-selections)
@@ -111,6 +111,15 @@ adapters and custom pair providers, and makes no transactional cancellation or
writer-interruption guarantee. Correct the prose rather than expanding runtime
enforcement or imposing new requirements on consumers.
**Completed 2026-10-12:** The CLI reference now describes preparation and provider
invocation generally, attributes ordered loader calls and native diagnostic
adaptation to the bundled ConfigKit adapters, and preserves custom provider and
application cache ownership. Empty report output is promised only for report
preparation failure or cancellation observed before delivery starts. Writer
interruption and rollback are not promised. The prose was checked against the
adapter and report execution paths; local links and whitespace checks passed.
No runtime enforcement or consumer requirement was added.
## R-3: Make preparation tests reject failure without freezing private storage
**Status:** Open. **Priority:** Medium. **Category:** Test quality /