diff --git a/docs/roadmap/audit-remediation.md b/docs/roadmap/audit-remediation.md index 1167c8a..13f46d1 100644 --- a/docs/roadmap/audit-remediation.md +++ b/docs/roadmap/audit-remediation.md @@ -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. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md new file mode 100644 index 0000000..57acc81 --- /dev/null +++ b/docs/roadmap/implementation.md @@ -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.