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

Plan the audit remediation sprint

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 15:30:02 +00:00
parent d492c77471
commit 118b49ee55
2 changed files with 658 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
docs/roadmap/audit-remediation.md
View File

@@ -1,7 +1,7 @@
# Audit remediation roadmap
Status: ready for implementation planning; no remediation implemented by this
document.
Status: target and decisions finalized; the [implementation plan](implementation.md)
defines the sprint. No remediation is implemented by these documents.
Baseline: `d131999c7c474010a4814bb81601cd32920e6c83`. The
[catalog](audit/catalog.md) contains 27 distinct open findings, five P2 and 22 P3,
@@ -11,8 +11,9 @@ rationale for this roadmap. The implementation is unchanged since the audited
state `db732e3a1de55c844f77870e1c6db683c2685d5d`; subsequent commits recorded
the review and decisions.
This roadmap owns the target, work grouping, dependencies, and completion
criteria. The catalog owns finding status and accepted remediation decisions;
This roadmap owns the target, scope, and completion criteria. The implementation
plan owns ordered stages, dependencies, concrete changes, and verification steps.
The catalog owns finding status and accepted remediation decisions;
the original audit entries own detailed evidence. This is separate from the
older, completed [shared-reporting remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/264b82bd5759f052a3646d57828945a87b7586d3/docs/roadmap/remediation.md), whose findings
are not reopened here. Unselected capabilities in [future work](future.md)
@@ -99,17 +100,14 @@ changes. Do not replace upstream domain behavior or expand validation merely to
simplify implementation. Private helper names and exact signatures are ordinary
implementation choices unless explicitly selected as public API.
## Work required
## Target capabilities and completion evidence
The groups below cover every catalog finding. They are reviewable work areas,
not a requirement to combine all changes in a group into one commit. Record
implementation evidence against each finding rather than treating a refactor
or a passing broad suite as proof that every nearby defect is fixed.
The areas below cover every catalog finding and define the desired end state,
without specifying implementation order. Each finding remains accountable for
its own remedy and evidence; a nearby refactor or passing broad suite alone does
not establish that a defect is fixed.
### 1. Correct outcomes, request ownership, and reporting lifecycle
Prioritize these fixes before maintenance refactors. Move any affected tests
off obsolete closure helpers as needed for F24 so they exercise real finalization.
### Correct outcomes, request ownership, and reporting lifecycle
| Finding | Required work | Evidence of the intended result |
| --- | --- | --- |
@@ -121,22 +119,22 @@ off obsolete closure helpers as needed for F24 so they exercise real finalizatio
| F07 | Clear direct destination references under the existing reporting lock after final presentation. | Closed handles still reject late operations, returned presentation evidence survives, and CommandKit no longer retains writers through those direct fields or closes them. |
F03 and F07 touch the same finalization boundary but fix different problems.
Keep them separately explainable. F20's later bookkeeping extraction must not
Keep them separately explainable. F20's bookkeeping extraction must not
be used as a substitute for either correction.
### 2. Restore examples and completion validation
### Working examples and completion validation
| Finding | Required work | Evidence of the intended result |
| --- | --- | --- |
| F06 | Remove the completion fixture's collision with core's reserved `format` flag. Use core's flag when testing report selection, or rename the fixture's custom choice flag when testing application completion. Adjust corresponding expectations. | The fixture constructs and generates scripts, and available opt-in shell checks exercise completion rather than failing during installation. |
| F08 | Assign the example's optional scenario argument only when supplied. | Bare `report` runs its `demo` default; an explicitly supplied value still reaches ordinary validation. |
Finish F06 before validating F16. Use the existing completion harness; its
prerequisites and commands belong to the [developer guide](../development.md#shell-completion-validation).
Report any unavailable shell checks accurately instead of treating skipped
checks as passed. This does not select a new platform support matrix.
The existing completion harness remains the validation owner; its prerequisites
and commands belong to the [developer guide](../development.md#shell-completion-validation).
Unavailable shell checks remain distinct from successful checks. This does not
select a new platform support matrix.
### 3. Clarify and simplify integration boundaries
### Clear and narrow integration boundaries
| Finding | Required work | Evidence of the intended result |
| --- | --- | --- |
@@ -156,7 +154,7 @@ For F23, ConfigKit's opaque path is already valid, but the concise report still
needs key-token decoding. Remove revalidation, not that necessary translation.
Use bounded single-pass escape decoding so `~01` becomes `~1`, not `/`.
### 4. Remove obsolete plumbing and consolidate private responsibilities
### Cohesive private responsibilities
| Finding | Required work | Evidence of the intended result |
| --- | --- | --- |
@@ -168,18 +166,17 @@ Use bounded single-pass escape decoding so `~01` becomes `~1`, not `/`.
| F17 | Separate cohesive scope capture/validation and selector attachment work; make operation bindings and discovery inventory construction explicit. | Captured ownership, retained errors, binding identity, discovery, and construction without provider acquisition remain intact. |
| F19 | Extract conversion-error attribution and operand preparation modestly, keeping flag preparation and occurrence ordering together. | Entered spelling, supplied-state distinctions, error identity, application order, and captured replay remain correct without replacing dense reconstruction or the existing merge algorithm. |
Apply the relevant pieces of F24 alongside the work they support, then verify
that the entire finding is addressed. Among the extraction work, favor F20,
then F18 and F17, keeping F19 conservative. Keep related loops together and use
existing prepared types. Tests should continue to protect behavior rather than
the number of helpers, incidental private call sequences, or complexity scores.
F24 covers all identified obsolete entry points. Extractions retain related
loops and existing prepared types; F19 remains conservative. Tests protect
behavior rather than helper counts, incidental private call sequences, or
complexity scores.
For F16, retain execution normalization and failure handling with the parser,
and partial-word handling and suggestions with completion. Keep caller-specific
branches where unification requires extensive modes or special cases. Repair
F06 first; this sharing introduces no new alias-completion behavior.
branches where unification requires extensive modes or special cases. This
sharing introduces no new alias-completion behavior.
### 5. Eliminate repeated alias and diagnostic-path work
### Efficient alias and diagnostic-path traversal
| Finding | Required work | Evidence of the intended result |
| --- | --- | --- |
@@ -188,11 +185,11 @@ F06 first; this sharing introduces no new alias-completion behavior.
| F15 | Query strict descendant sources through that same tree for each existing intermediate resolution path. | Help avoids full-catalog scans for unrelated sources while preserving authoritative resolution, longer overrides, canonical-target checks, suffix deduplication, and output order. |
| F22 | Use a scratch path during declaration validation and format full paths only for emitted diagnostics. | Successful validation avoids eager full-path formatting, while retained issues, error identity, child order, and absent/root-only declaration handling remain correct. |
Implement F14 and F15 as one coordinated change to internal read-only tree
operations. Keep nodes private, captured paths owned correctly, and the existing
F14 and F15 share internal read-only operations on the existing resolver tree,
with private nodes, correctly owned captured paths, and the existing
routing-snapshot lifetime. Root help may still use the complete catalog when
all entries are needed. Do not add a second index, a persistent result cache,
new alias limits, or alias-completion features as part of these fixes.
all entries are needed. No second index, persistent result cache, new alias
limits, or alias-completion features are selected.
Source-level review should establish removal of the identified repeated work;
behavioral checks establish preserved results. No performance threshold or
@@ -200,7 +197,7 @@ benchmark suite is required to justify these remedies. Other routing,
termination-analysis, formatting, and installation costs remain outside those
specific complexity improvements.
### 6. Finish documentation consistency and close findings
### Consistent current guidance and historical navigation
| Finding | Required work | Evidence of the intended result |
| --- | --- | --- |
@@ -208,34 +205,28 @@ specific complexity improvements.
| F26 | Keep a brief module/status orientation in README and link the consumer guide for exact compatibility and installation details. | Volatile compatibility guidance has one canonical owner. |
| F27 | Add a useful forward-only correction identifying the correct pinned consumer-guide section for the historical ckprompt note. | The correction points to the actual section without modifying the published tag, historical note, or hosted release contents. |
Update GoDoc, CLI documentation, examples, and focused internal documentation
with the implementation they describe, rather than postponing those updates
until this last group. Check links and semantic claims. Keep existing audit
evidence available and record each finding's implementation/verification result
in the catalog. A selected remedy alone does not close a finding.
GoDoc, CLI documentation, examples, and focused internal documentation must
describe the implemented boundaries, with valid links and semantic claims.
Existing audit evidence remains available; the catalog records each finding's
implementation/verification result. A selected remedy alone does not close it.
## Verification and module alignment
Use the narrowest existing behavioral checks that cover each change; add focused
regressions for consequential defects where existing checks do not expose them.
Reuse successful results for unchanged content. Remove tests that sustain deleted
machinery while retaining useful contract coverage. Assertions should establish
CommandKit's adaptation and coordination, not independently test upstream domain
correctness or turn private mechanics into public guarantees.
Verification establishes CommandKit's adaptation and coordination, without
independently testing upstream domain correctness or turning private mechanics
into public guarantees. Consequential defects have focused behavioral protection;
useful contract coverage survives deletion of obsolete test machinery. The
implementation plan defines proportionate checks and when to run them.
For F03, use controlled synchronization to reproduce the acceptance/finalization
boundary rather than timing sleeps. A focused race-enabled run can supplement
that check, but a race detector alone cannot establish correct queue ordering.
For F07, inspect unnecessary reference retention without creating a garbage
collection timing promise. Keep ordinary suites deterministic, offline, and
independent of credentials or live model services.
For F03, acceptance/finalization evidence must establish queue ordering; a race
detector alone cannot do so. F07 does not establish a garbage collection timing
promise. Ordinary suites remain deterministic, offline, and independent of
credentials or live model services.
Follow the [developer guide](../development.md#documentation-validation) for
module and workspace test commands. The root suite does not traverse the nested
modules. Validate changed modules during their work, then the combined local
source through the aligned workspace, including representative maintained
consumers and the repaired completion checks where available. Use Go 1.27.0
for this cross-module work as already selected by the repository.
The [developer guide](../development.md#documentation-validation) owns module and
workspace test commands. The root suite does not traverse nested modules.
Evidence covers combined local source, representative maintained consumers,
and available repaired completion checks using the already selected Go 1.27.0.
The independent-module check has a concrete dependency constraint: ckprompt's
new F21 call will not exist in its currently selected ckconfig v0.4.0 dependency.

610
docs/roadmap/implementation.md Normal file
View File

@@ -0,0 +1,610 @@
# Audit remediation implementation plan
Status: planned; no stage implemented by this document.
Baseline: `d492c7747175c01a53261206c2b4356e53453621`. Source remains the audited
implementation; intervening changes recorded decisions and retired the completed
older remediation. The [roadmap](audit-remediation.md) owns the target and scope,
the [catalog](audit/catalog.md) owns accepted decisions and finding status, and
its original audit links own defect evidence. The
[analysis](audit/remediation-analysis.md) explains the selected designs.
## Instructions for the implementing agent
Execute Stage 1 through Stage 23 in order as one sprint. Each stage is sized as
one bounded Luna assignment; stages 11–12 split the cross-module diagnostic
change. Intermediate stages need not compile independently. If a check depends
on a later stage, record it as pending and run it when its prerequisites exist;
do not add temporary compatibility machinery to make an intermediate stage green.
The final source must be coherent and validated through the aligned workspace.
Read [development guidance](../development.md) and the applicable
[agent](../policy/agents.md), [architecture](../policy/architecture.md),
[testing](../policy/testing.md), and [documentation](../policy/documentation.md)
policies. Preserve core/backend isolation and application/upstream ownership.
This sprint selects no upstream upgrades, toolchain requirement changes, new
commands, report formats, arbitrary input limits, or concurrent App dispatch.
Keep the existing safe evidence, error identity, presence, and independent
comparison-input semantics. The selected public changes need no consumer
migration scaffolding. Private helper names and signatures may follow idiomatic
implementation; the explicit responsibilities below are the decisions to retain.
Relevant accepted boundaries are [ADR 0002](../adr/0002-public-facade-and-cli-backend.md),
[ADR 0004](../adr/0004-optional-integration-modules.md), and
[ADR 0006](../adr/0006-invocation-reporting.md). Use repository graph discovery
before textual code searches as directed by AGENTS.md.
For every stage, inspect its source and the catalog's linked originals before
editing. Reuse existing tests; extend them only for meaningful missing coverage.
Consequential correctness fixes need focused regressions that demonstrate the
original defect. Refactor tests only where they depend on removed mechanics;
do not rewrite behavioral expectations to accommodate accidental changes. Test
CommandKit adaptation and coordination, trusting upstream domain contracts.
Update the owning GoDoc, CLI, consumer or internal documentation with each change.
Record stage completion and actual verification here. Add completion evidence to
the corresponding catalog finding only after its entire remedy is implemented
and verified. F21 spans stages 11–12; F24 spans stages 3, 13, and 20. Preserve the
original audits and accepted decisions. Commit completed nonempty work units with
plain English messages under repository policy; do not publish or push.
## Validation conventions
Use the cached Go 1.27.0 toolchain for cross-module checks. Preserve ignored
`go.work` and `go.work.sum`. In the aligned three-module workspace, run focused
tests for the affected package during the stages; select existing test names from
the named test files plus new defect regressions. Use `GOTOOLCHAIN=local`,
`GOPROXY=off`, and `-mod=readonly` for offline checks with cached dependencies.
If the default cache is not writable, use a temporary `GOCACHE` under `/tmp`.
Format changed Go files with gofmt. No benchmarks, timing thresholds, complexity
score targets, or new validation framework are needed.
Focused workspace commands run from the repository root. Select the stage's
relevant tests with `-run` when existing coverage permits; the package targets
are `.` for core, `./internal/cobra` for the adapter, `./internal/alias` for the
resolver, `./integrations/ckconfig` and `./integrations/ckprompt` for integrations.
For example, reporter checks use
`GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly -run 'TestReporter|TestHiddenDeferred' .`.
Example package targets follow their paths under the corresponding module.
Stage 23 owns the final broad checks. Root `./...` excludes nested modules.
Workspace results cover current combined sources; independent checks with
`GOWORK=off` cover each manifest's selected dependencies. After stage 12,
ckprompt's new helper call cannot compile against its selected ckconfig v0.4.0.
Do not change manifests to invented versions, fabricate sums, or commit local
replacements. Validate combined source in the workspace, and record that released
module alignment remains pending. Temporary external-consumer modules or alternate
module files may use explicit local replacements as additional boundary evidence;
label them as local-source checks. Once appropriate releases exist, dependency
alignment and independent validation follow the [release procedure](../release.md)
as separate work. Publication is neither authorized nor a prerequisite here.
## Stage 1 — Retain aggregate smoke cancellation
Findings: F01. Primary source: `integrations/ckprompt/smoke_command.go`.
1. In runSmokeAggregate, retain cancellation observed at the later checkpoint
when it omits remaining smoke kinds. Join it with prior operation causes;
avoid redundantly adding cancellation already retained by an operation.
2. Preserve attempted-kind order, acquired reports, diagnostics, prior errors,
and explanations. Do not invent reports for unattempted kinds. Keep the
existing acquisition/cancellation handling and final reporting path.
3. Do not add a blanket late-cancellation failure after all requested work is
complete. Distinguish the final completed kind from a stop that omits work.
4. Extend smoke aggregate/outcome tests using a progress writer that cancels
without reentering the Reporter. Assert a failed partial outcome and
errors.Is for cancellation, both with and without an existing provider error.
Check omitted callbacks, preserved evidence, and ordinary successful all-kind
execution. Keep the ordinary suites offline.
Complete when the progress-delivery cancellation window cannot produce a
successful incomplete aggregate or lose cancellation beside another cause.
## Stage 2 — Isolate parsed provider-parameter JSON
Findings: F02. Sources: ckprompt `request_flags.go` and `smoke_command.go`.
1. Add one private recursive copier for the known CLI JSON object/array
representation. Copy maps and arrays; preserve scalar numeric types and
nil versus explicitly empty collections. Do not JSON-marshal to copy values.
2. Use it when applying NewExecutionFlags.ExtraParams to a destination and when
smokeRequestForKind copies each aggregate execution seed. Retain existing
scalar-pointer copies and authoritative application builder replacements.
3. Keep this out of generic core ValueFlag/captured-binding machinery. Do not
promise cloning of arbitrary application object graphs or repair sharing
introduced by application builders.
4. Extend request flag and smoke tests: mutate a nested map/array in one request
and inspect the next kind's original values; separately apply captured flags
to independent destinations using ApplyTo and ApplySuppliedTo, mutate one,
and confirm the other retains supplied values. Cover empty/nil and the current
CLI numeric representation without retesting upstream preparation.
Complete when both binding replay and per-kind seed boundaries are isolated.
## Stage 3 — Close deferred acceptance atomically
Findings: F03 and the reporter-lifecycle portion of F24. Source: `reporter.go`.
1. Add a private deferred-acceptance/finalization state distinct from the final
closed state. Under the existing mutex, end acceptance and detach the batch
in one transition at the start of finalize.
2. Make DeferredReporter.enqueue return ErrReporterClosed after that transition,
including hidden or empty submissions. Retain pre-cutoff visibility and detail
handling. Keep finalizer-owned batch delivery, completion reporting, and
terminal explanations usable until final closure.
3. Do not repeatedly drain arrivals or wait for application producers. Do not
set the general closed flag before internal presentation finishes. Ordinary
concurrent Reporter operations retain their existing lifecycle.
4. Move tests using the synthetic close/setVisibility helpers to actual
finalize/applySelection entry points, preserving useful assertions. Remove
those obsolete production helpers once their callers have moved. Keep any
concise setup helpers in `_test.go`, delegating to the real paths.
5. Extend reporter finalization tests with channels controlling a destination's
flush boundary. Submit a deferred message while the accepted batch is being
presented; assert ErrReporterClosed. Check pre-cutoff accepted delivery,
completion/terminal ordering and visibility, plus render/write failure
evidence. Avoid sleeps and callback reentry. Run the focused reporter tests
with `-race -count=1` as well as ordinary focused checks.
6. Document the cutoff in Reporter/AtEnd GoDoc and relevant reporting guidance.
Complete F03 when acceptance cannot succeed into an abandoned batch. Keep F24
open for the remaining parsing and binding wrappers.
## Stage 4 — Reject missing prepared-request results
Findings: F04. Source: ckprompt `preparation.go`.
1. After the existing provider-error and cancellation handling in
runRequestPreparation, reject a nil acquired.Value with an operational failure.
Use the neighboring missing-result handling style; retain supplied diagnostic
and explanation evidence and existing error identities.
2. Keep core null-report support and valid preview/report-plus-error handling
unchanged. Do not add new checks to upstream prepared-request contents.
3. Extend preparation tests through the public command: nil result/nil error,
valid result, and existing provider error/cancellation paths. Assert failure
classification and absence of a successful null preview, with retained
diagnostic/explanation evidence. Reuse core's existing null-report coverage.
Complete when empty successful acquisition cannot masquerade as prepared preview.
## Stage 5 — Separate show preparation cancellation from rendering failures
Findings: F05. Source: ckconfig `show.go`; reference `operations.go`'s
renderPreparedConfigReport checkpoint pattern.
1. Keep buffered effective-document preparation under managed rendering so
genuine native-writer/DecodeYAMLReport failures remain presentation evidence.
2. Capture cancellation observed by preparation checkpoints separately; return
nil from the renderer for a cancellation-only stop, then return configFailure
with that cancellation outside it. Do not deliver an incomplete report.
3. Preserve genuine native-writing/decoding errors even when cancellation is
also visible. Do not discard cancellation identity or alter the distinction
between interrupted preparation and cancellation after delivery starts.
4. Extend `report_cancellation_test.go`: two acquired scopes, first writer emits
valid YAML and cancels while returning nil, second writer remains uncalled.
Assert no output, cancellation Cause, and no manufactured RenderError or
WriteError. Reuse real render/write failure and focused-show coverage.
Complete when cancellation alone is not a presentation error and actual
presentation failures remain separately observable.
## Stage 6 — Repair the maintained consumers
Findings: F06 and F08. Sources: `testdata/completion/main.go`,
`completion_shell_test.go`, and `examples/core/main.go`.
1. Rename the fixture's custom `format` choice flag to `choice`; retain its
text/yaml choices. It tests application-owned completion, so keep it separate
from core's actual format flag. Update the root consumer harness inputs,
expected argv, prefix case (`--cho`), and terminal invocation consistently.
Do not rename unrelated backend fixtures or core's reporting flag.
2. Generate scripts from this fixture to prove App construction succeeds.
Run the opt-in consumer and backend shell checks available locally using the
developer guide's shell-completion commands. Record missing prerequisites or
shells as unavailable; do not count skips as successful interactive checks.
3. Guard the example scenario assignment with Supplied.Set, retaining the factory
default and explicitly supplied empty-value validation. Exercise bare
`go run ./examples/core report`, explicit demo, and an invalid scenario.
Reuse example coverage; no new default suite inventory is required for this
small example correction.
Complete when the example default works and the completion fixture reaches
script/shell validation. Stage 14 relies on this repaired fixture.
## Stage 7 — Release finalized reporter destination references
Findings: F07. Source: `reporter.go`; builds on stage 3.
1. After deferred/completion/terminal presentation and capture of observations,
mark state closed and clear both direct destination writer references while
holding the existing mutex. Retain closed state and errors/observations.
2. Do not Close/Flush either borrowed writer. Keep ErrReporterClosed behavior for
retained Reporter, Output, and DeferredReporter handles. Return the same
error identities; error objects may legitimately retain their own data.
3. Extend actual-finalization tests for success, operational failure, and
cancellation. Inspect that unnecessary direct references are released and
late operations reject without touching writers. Reuse caller-writer
ownership and presentation-evidence checks. Avoid GC-timing assertions in
ordinary tests; a temporary reachability probe is supplementary only.
Complete when finalized handles no longer keep destinations through those fields,
without promising immediate garbage collection or taking ownership of closers.
## Stage 8 — Share reporter detail-rendering bookkeeping
Findings: F20. Source: `reporter.go`; follows lifecycle fixes in stages 3 and 7.
1. Extract a private helper running under the existing reporting lock to invoke
detail callbacks through the managed writer and return render/write errors
separately, retaining first errors and their joined evidence as currently done.
2. Use it from renderTerminalLocked and submitMessageLocked. Keep headings,
visibility/discard selection, leading-message failures, destination delivery
observations, and terminal timing in the callers.
3. Preserve nil details, order/lifetime, hidden callbacks against io.Discard,
sticky destination failures and callback non-reentrancy. Add no locks or
configurable rendering pipeline.
4. Run focused reporter tests for hidden details, terminal/deferred ordering,
joined renderer evidence, independent destination failures and closed handles,
including stage 3's regression. Extend only uncovered behavioral cases.
Complete when both paths use one implementation of the delicate detail policy.
## Stage 9 — Clarify configuration evidence and narrow explanation providers
Findings: F09 and F11. Sources: ckconfig `contracts.go`, `show.go`, `explain.go`,
`contracts_adapter_test.go`; core `report_value.go` conversion GoDoc.
1. Document EffectiveWriter's single supported safe-YAML-document handoff and
link DecodeYAMLReport as the conversion contract owner. Clarify that formatting,
comments and framing are not passed through; document unsupported tags,
non-string mapping keys and multiple documents at the owning helper as needed.
Correct View's description to reflect acquired evidence used to build reports.
2. Reduce ExplanationReader to Explain(configkit.Path) (configkit.Explanation,
bool). Update its GoDoc and remove writer-only provider stubs/assertions and
direct interface-writer test calls across the repository.
3. Retain native objects' own writer methods. Do not add compatibility adapters,
another writer interface, or restore provider-owned report rendering.
4. Reuse acquired-explanation cross-format and delivery-error tests. Ensure a
custom provider implementing only Explain works for explanation/path show.
Reuse YAML conversion tests and review GoDoc against current conversion rules;
do not expand accepted YAML types to accommodate old wording.
5. Update affected consumer integration guidance for the selected provider API.
Complete each finding independently: accurate effective-output documentation for
F09, and acquisition-only provider wiring with preserved rendering for F11.
## Stage 10 — Document the selected flag declaration contract
Findings: F10. Source: `command.go` FlagMeta and related rename/alias GoDoc.
1. Define long names once with FlagMeta: nonempty Unicode lowercase-letter or
digit segments separated by single hyphens. Numeric-only and digit-leading
names remain valid. Describe the implemented reserved names help, quiet,
verbose, debug, progress and format.
2. Describe optional one-byte short spellings, excluding `-` and reserved `h`.
Do not apply the long-name lowercase rule to short spellings.
3. Link RenameFlag and flag-alias helpers to that declaration contract. Retain
CLI operator syntax in its existing owner and installation-time error timing.
4. Compare prose with validateBindings/validFlagName and the accepted catalog
decision. Make no runtime validator changes, normalization, ASCII-only rule,
or new tests solely to restate documentation.
Complete when exported guidance accurately states the already selected rules.
## Stage 11 — Export the shared ConfigKit diagnostic adapter
Findings: F21, ckconfig portion. Source: ckconfig `configkit_adapter.go`.
1. Expose the existing configKitDiagnosticsWithHeading responsibility as:
```go
func AdaptDiagnostics(heading string, sources []configkit.SourceInfo,
records []configkit.Diagnostic) ([]commandkit.Diagnostic, commandkit.Explanation)
```
2. Route ckconfig's ordinary and comparison-side adaptation through it. Keep any
small scope-to-heading constructor that serves a caller; remove the replaced
duplicate implementation rather than leaving parallel helpers.
3. Retain captured sources, cloned Primary/Related locations, grouping of error
records into explanation details and other records into ordinary diagnostics,
within-group order, source legends, native formatting and short-write handling.
4. Document that it returns captured CLI presentation evidence; it does not print
immediately, acquire configuration, determine outcomes, or schedule messages.
5. Reuse native adapter tests, extending public helper coverage for mutations of
input slices/locations after adaptation and deferred rendering failures where
those protections are not already exercised. Assert CommandKit's snapshots
and classifications, not ConfigKit's diagnostic formatting algorithm.
Keep F21 open until stage 12 removes the other integration's duplication.
## Stage 12 — Adopt shared diagnostics in ckprompt
Findings: F21 completion. Source: ckprompt `adapters.go` and related tests.
1. Make promptKitDiagnostics call ckconfig.AdaptDiagnostics. Preserve its current
heading: `Configuration scope ` plus strconv.Quote(scope), optional
` (side)`, and the existing colon/newline. Supply that complete heading to
the shared helper, whose writer consumes it as provided.
2. Translate the returned diagnostics/explanation into the existing private
acquisition record. Remove the duplicated snapshot/severity partition and
writePromptKitDiagnostics implementation and now-unused imports.
3. Keep operation-specific fallback explanations, causes, outcomes, scope/side
labels, and both integrations' scheduling switches with their callers. No
new core dependency or shared module is required.
4. Run focused ckprompt acquisition/comparison tests in the aligned workspace,
covering available/empty evidence, warning versus error adaptation, side
labels, cause retention and deferred writer failure. Verify integration
documentation describes the new helper only under ckconfig's CLI ownership.
5. Record the independent ckprompt limitation stated in Validation conventions;
do not conceal it with committed replacements or conditional fallbacks.
Complete F21 when both callers share one adapter and preserve their context.
## Stage 13 — Remove unused parser resource plumbing
Findings: F12 and parsing portion of F24. Sources: `execute.go`, `parser.go`,
`internal/commandmeta/metadata.go`, and `internal/cobra/parse.go`.
1. Remove execution.streams and ParseOptions.Context/In/Out/Err, then remove their
unused propagation/default normalization from the adapter. Retain consumed
alias-selection options. Normalize invocation streams once with the reporter.
2. Keep Invocation.Context and real reporter destinations unchanged. Set explicit
internal discard output/error destinations on the backend and preserve local
RenderHelp buffering; Cobra defaults must not write to process destinations.
Preserve runnable markers, help metadata, fresh sessions and session reuse
within one invocation. Remove only settings associated with unused resources.
3. Replace App.parse's test-only path with current execution/session preparation
in its test and remove the obsolete wrapper. Keep concise test setup in tests.
4. Adapt session tests to the smaller options shape, retaining behavioral help,
routing, parser-state isolation and context-forwarding coverage. Run core and
adapter focused tests; confirm help is delivered through core reporting.
5. Update focused internal documentation for the simplified parser boundary.
Keep F24 open until the binding wrappers are handled in stage 20.
## Stage 14 — Share internal flag-consumption facts
Findings: F16. Sources: `internal/commandmeta/flags.go`,
`internal/cobra/flags.go`, and `completion_flags.go`; stage 6 is prerequisite.
1. Extend the existing neutral helpers with a small consumption operation over
lookup, token and short-cluster position. Return flag identity, attached value
presence separately from its text, next-argument need, and cluster continuation.
Use each caller's existing lookup; keep `--` classification/end handling clear.
2. Migrate interpretFlagTokens, walkCompletionFlags and completionOptionTarget
to these facts. Execution retains canonical normalization, entered spellings,
occurrences, consumed failure prefixes and backend errors. Completion retains
unfinished-word interpretation, pending values, suggestions and insertion text.
3. Preserve boolean assignments, attached/next values (including option-looking
values), explicit empties, unknown spellings and short-cluster boundaries.
Keep caller-specific branches where sharing would require extensive modes.
4. Reuse parser, alias/provenance and public completion tests; extend uncovered
cases that compare shared grammar and intentionally different missing/partial
input behavior. Run available repaired shell checks. Do not add alias discovery,
public parser APIs, execution/completion modes, or a replacement backend.
Complete when common grammar mechanics have one owner and caller policies remain
clear, with selected syntax and provenance preserved.
## Stage 15 — Memoize each context's flag-alias graph
Findings: F13. Source: `flag_aliases.go`.
1. Replace independent suffix walks with context-local visitation and memoized
terminal results, including unavailable endpoints. Resolve canonical spellings
before following a mapping of that spelling. Cache token resolution without
conflating a source's collision check with its target's resolution.
2. Process the existing sorted sources, resolving each mapping's target before
the active-source collision check. Keep scoped overrides, inactive globals,
scoped missing-target failures and useful participating-cycle diagnostics.
Maintain an active traversal stack to identify cycles; no hop cap is needed.
3. Keep the cache invocation/snapshot preparation local to its effective context,
revalidating on registration. Do not share results across different contexts.
4. Run existing flag-alias chain, cycle, duplicate/scope and discovery tests;
add representative shared-suffix/inactive-endpoint coverage only if missing.
Review loops to confirm each target suffix is resolved once per context.
Existing sorting remains; no benchmark or whole-installation bound is required.
Complete when repeated suffix traversal is removed without routing changes.
## Stage 16 — Reuse the resolver tree for prefix discovery and help
Findings: F14 and F15, one coordinated change. Sources:
`internal/alias/resolver.go`, `flag_aliases.go`, and `help_view.go`.
1. Add two narrow internal read-only tree operations: enumerate distinct nonempty
proper source prefixes, and find mapping sources strictly below a supplied
prefix. Reuse trie nodes and their captured paths; keep nodes private and
return owned paths/mappings so consumers cannot mutate the resolver.
2. For enumeration, visit each eligible tree node once rather than rebuilding
each declaration's prefixes. A node may itself end an alias and have children;
leave exact-alias exclusion to the existing classification. Apply canonical,
exact-source and canonical-operand-space exclusions once per distinct prefix.
Update discoverFlagContexts's consumed resolver shape accordingly.
3. For descendant lookup, locate the supplied prefix branch and enumerate only
descendants, excluding that node's mapping. Use it for every existing
ResolutionPaths entry in routeHelpAliases. Keep root help's complete catalog
when needed, composed-path authoritative resolution, canonical-target checks,
longer overrides, suffix deduplication and sorted presentation.
4. Reuse routing snapshot lifetime, without another index or result cache. Do
not replace the resolver's selected termination proof or longest-prefix rules.
5. Check shared deep prefixes, alias chains with no descendant output, exact
aliases with children, longer overrides, canonical operand exclusions and
post-registration refresh using existing alias/help/discovery coverage plus
missing focused cases. Inspect traversal to establish reduced repeated work;
assert results rather than timing or private call counts.
Record evidence separately for F14 preparation and F15 repeated help lookup.
Neither finding closes merely because the new tree methods exist.
## Stage 17 — Format declaration paths only for diagnostics
Findings: F22. Source: `command.go` collectDeclarationIssues.
1. Traverse with one scratch append/truncate path. Construct an owned formatted
label only when emitting a retained issue or root-only-placement diagnostic.
Do not capture mutable scratch slices in stored errors or declarations.
2. Preserve child/issue order, error wrapping and identity, and absent/invalid
declaration handling. Keep other capture/installation phases unchanged.
3. Reuse registry/declaration tests for invalid children, root-only placement,
retained errors and valid nested trees. Review that the successful walk no
longer copies/formats every ancestral path. No timing test or new installation
performance guarantee is required.
Complete when diagnostic scratch work is proportional to the traversal and
actual emitted paths rather than every valid full path.
## Stage 18 — Separate configuration operation preparation
Findings: F18. Source: ckconfig `input.go` and its command builder.
1. Extract operation-specific option checks, shared scope/capability selection,
and independent comparison-side preparation into small private functions over
existing types. Keep an explicit orchestration function and ordinary branches.
2. Extract cohesive flag groups where they clarify command construction. Preserve
bare explain help, supplied-state distinctions, full aggregate capability
preflight, binding application, and both input checks before shared state
construction/acquisition. Do not invent a plan hierarchy or rule registry.
3. Run existing operation-preflight, help/no-loading, scope-selector and comparison
preparation tests. Confirm independently initialized equal selections and
failure classifications remain correct. Retain stage 5's show protection.
Complete when ordinary and comparison paths can be followed separately without
changing the selected lifecycle or adding machinery solely to shorten functions.
## Stage 19 — Separate configuration suite capture responsibilities
Findings: F17. Source: ckconfig `family.go` captureSuite.
1. Extract cohesive scope capture/validation and selector capture/attachment;
make operation binding unions and discovery inventory construction explicit.
Reuse preparedSuite/preparedScope and keep related loops together.
2. Retain declaration copies, scope order, accumulated error order, selector and
binding identity, comparison requiredness, empty-suite handling and availability.
Setup remains metadata-only: no input factories, state or provider acquisition.
3. Run family wiring/capture, operation selector and comparison contract tests.
Reuse mutation-after-capture and help/discovery checks. Avoid new indexes or
intermediate records merely to split the function into phases.
Complete when each capture responsibility has a clear place and behavior holds.
## Stage 20 — Simplify typed preparation and retire remaining test wrappers
Findings: F19 and completion of F24. Sources: `binding.go`, `flag_values.go`,
`parser.go` and related tests; review reporter cleanup from stage 3 as well.
1. Extract entered-spelling conversion-error attribution and operand preparation
from prepareInputWithOccurrences. Keep flag preparation, ordinal identity and
dense reconstruction together, in the orchestration function if appropriate.
2. Preserve conversion before input construction, ordinary/ordered/argument setter
order, fallback versus parser-log ordering, deferred required checks, original
binding identity, supplied states, error identity and the existing replay heap
merge. Do not introduce a new state container or replay framework.
3. Move tests from prepareInput/prepareInputWithSpellings to occurrence-aware
preparation and remove those obsolete production wrappers. Any small setup or
read-only observation helpers used solely by tests belong in `_test.go`.
4. Confirm all F24 targets: reporter setVisibility/close, App.parse and both
preparation wrappers have been retired without losing useful assertions.
Use graph call traces supplemented by text references where necessary; absence
from one graph query alone is not proof of no callers.
5. Run binding conversion/error, typed composition, ordered occurrence, nested
capture, reversed/subset/duplicate selections and both replay-method tests.
Reuse actual reporter lifecycle and routed-parser checks from prior stages.
Complete F19 for the bounded extractions and F24 for all obsolete entry points;
record these outcomes separately.
## Stage 21 — Decode native diff paths without revalidation
Findings: F23. Source: ckconfig `diff_report.go` and diff report tests.
1. Change the private token helper to accept configkit.Path. Split its canonical
JSON Pointer representation, preserving root versus the empty-key token.
Decode `~1` and `~0` in one pass, for example with strings.NewReplacer.
`~01` must become `~1`, never `/`.
2. Remove arbitrary-string validation branches/error returns and corresponding
unreachable malformed-string tests. Preserve real snapshot decoding errors,
configkit.ParsePath for operator input, and the selected concise diff projection.
3. Reuse diff report token/render coverage for root, empty/numeric/dot/percent/
Unicode/slash/tilde keys, present null/deletion, structural values and malformed
present snapshots. Keep upstream path validity owned by ConfigKit.
Complete when native-path adaptation retains needed translation without duplicate
validation or a new public pointer utility.
## Stage 22 — Correct current documentation and historical navigation
Findings: F25, F26 and F27.
1. In ADR 0006's Status section, explicitly mark remaining pre-implementation
lifecycle wording as historical and point current contracts to GoDoc and the
CLI reference. Preserve the accepted decision text rather than rewrite it or
create a replacement ADR. Check readers no longer infer reporting is pending.
2. In README retain brief status/module orientation and a link to the consumer
guide's module-selection section. Remove the duplicate exact compatibility
matrix; keep the consumer guide as its owner. No dependency changes follow.
3. Add `integrations/ckprompt/docs/releases/errata.md` with a brief forward-only
correction for v0.2.0's consumer-guide section link. The corrected target is
the existing pinned v0.2.0 guide with fragment
`#promptkit-configuration-definitions-and-requirements`. Link this correction
from the developer guide's completed-history navigation so it is discoverable.
Preserve the old note, immutable tag and hosted release contents.
4. Verify the corrected fragment against the local tagged Git object, all new
local paths/fragments, and the semantic claims of the edited prose. Run
documentation whitespace checks. Do not republish or contact hosted services.
Complete when present guidance and useful historical navigation have clear owners.
## Stage 23 — Verify the assembled sprint and record completion
Findings: all F01–F27; no new feature work.
1. Review the full diff against this baseline and all roadmap completion criteria.
Verify every finding has its remedy and relevant evidence, including both
F14/F15 costs, both F02 boundaries, all F24 wrappers, and both F21 callers.
Check tests added for P2 defects fail against their original behavior and
exercise the actual public/package lifecycle; avoid exact incidental wording.
2. Run the full aligned current-source workspace suites from the root:
```sh
GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly ./... ./integrations/ckconfig/... ./integrations/ckprompt/...
```
Run focused reporter race checks for the final reporting changes. Broaden or
repeat tests only for changed content, failures or unresolved concerns.
3. Run independent suites from the root and each integration directory with
`GOWORK=off GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly ./...` when
their selected dependencies support the changes. Record exact selections.
After F21, explicitly record ckprompt's expected missing-helper limitation
against ckconfig v0.4.0; it is not a workspace regression and is not a passed
independent check. Do not silently switch dependencies for that claim.
4. Exercise representative maintained consumers: the core reporting default,
ckconfig ordinary/all-scope show and two-sided diff, and the composed ckprompt
prepared preview and fixture-backed aggregate smoke operation. Use the
developer guide and example READMEs for actual invocations. Run available
opt-in shell checks following repaired fixture/grammar changes; record skips
and environment limits accurately. No live model/service or credential use.
5. Confirm owning GoDoc/CLI/consumer/internal docs match the final code; validate
local Markdown links and fragments, pinned historical links through Git,
provenance and absence of template residue. Run tracked and staged Markdown
whitespace checks from the developer guide. Ensure source is gofmt-clean and
ignored workspace files, upstream versions and Go requirements were preserved.
6. Record each finding's completed source work and actual checks in the catalog,
stage completion here, and target completion in the roadmap. Clearly preserve
pending release/dependency alignment as release work in the existing future
record; source remediation must not be described as independently released.
Do not retire unresolved findings or mark unavailable checks passed.
7. Review status, stage only sprint changes and commit remaining completed units
with plain English messages. Report the final source result, validation,
pending release alignment, commit identifiers and worktree state. No release,
push, or publication is part of this sprint.
Complete when the targeted source state and its verification are evidenced,
with external release alignment explicitly distinguished from source completion.
## Open Questions
None. Product, ownership and remediation choices are resolved in the catalog
and roadmap. Publication versions remain separate release work. Routine private
helper signatures and test organization are implementation choices within the
boundaries above, not blockers requiring another design round.