base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 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 ### Compare configuration selections
`config diff` compares two independently loaded selections for one scope that `config diff` prepares two selections for one scope that declares comparison
declares comparison. The default scope is `app`; `--scope all` is unsupported. 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 The PromptKit engine scope does not currently declare comparison, so selecting
`--scope promptkit` is a usage error. `--scope promptkit` is a usage error.
`--config` and `--overlay` select the left side. `--against-config` and `--config` and `--overlay` select the left side. `--against-config` and
`--against-overlay` independently override the right side. When a right-side `--against-overlay` independently override the right side. When a right-side
field is omitted, it inherits the corresponding left value and supplied state; field is omitted, it inherits the corresponding left value and supplied state;
an explicit empty string overrides it and remains supplied. Equal selections are 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; YAML is the only format and the default. Explicit `--format yaml` is accepted;
`text` and other formats are usage errors. For example: `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. Successful comparisons return status `0`, including concealed or empty results.
Unsupported scopes and format errors are usage errors; input checks retain the Unsupported scopes and format errors are usage errors; input checks retain the
existing usage/operational classification. Load and native comparison failures existing usage/operational classification. Load and native comparison failures
are operational and preserve supported error identity. Comparison are operational and preserve supported error identity.
diagnostics identify their left/right side and source legend. The adapter loads
left before right, retains left diagnostics if right loading fails, and gathers The bundled `FromConfigKit` and `AppCommand` adapters invoke the supplied loader
both loads' diagnostics before native comparison. The complete report is for each reached side, left before right, then call native comparison. They label
prepared before writing. Cancellation and preparation failures leave report native diagnostics with their left/right side and source legend, retain left
output empty; an output error or short write uses the existing incomplete-report diagnostics if right loading fails, and gather both loads' diagnostics before
delivery outcome. 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 ## PromptKit definition inspection

13
docs/roadmap/remediation.md
View File

@@ -1,6 +1,6 @@
# Configuration comparison review remediation # 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. follow-up work and its completion evidence.
## Review baseline and scope ## 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 ## 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. contracts / documentation accuracy.
**Evidence:** The [comparison CLI reference](../cli.md#compare-configuration-selections) **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 writer-interruption guarantee. Correct the prose rather than expanding runtime
enforcement or imposing new requirements on consumers. 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 ## R-3: Make preparation tests reject failure without freezing private storage
**Status:** Open. **Priority:** Medium. **Category:** Test quality / **Status:** Open. **Priority:** Medium. **Category:** Test quality /