commandkit/docs/roadmap/implementation.md

# Audit remediation implementation plan

Status: in progress; Stages 1–9 complete.

Baseline: `d492c7747175c01a53261206c2b4356e53453621`. Before this sprint,
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

Once the user approves this sprint, execute Stage 1 through Stage 23 in order
under that approval. Stages are bounded work units within one continuous run,
not separate prompts, approval gates, or handoffs. Proceed to the next stage
without asking for confirmation after a stage, test run, or local commit.
Keep progress updates concise and report the assembled result after Stage 23.
Stages 11–12 split the cross-module diagnostic change for implementation clarity.

Intermediate stages need not compile independently. If a check depends on a later
stage, record it as pending, continue in order, and run it when its prerequisites
exist. Stage completion criteria describe what must eventually be evidenced;
they do not require stopping for dependent verification before later work can
proceed. Do not add temporary compatibility machinery to make an intermediate
stage green. The final source must be coherent and validated through the aligned
workspace.

Resolve ordinary implementation choices and fix failures within the approved
scope without another design round. A real contradiction in the selected target
or an unavoidable external blocker may require input; first investigate in-scope
remedies and complete remaining independent work. Do not silently change the
target, waive a relevant failing check, or claim blocked work is complete.

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; a commit is not a user-review
checkpoint. Related stages may form one validated commit when needed. 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.
Do not wait for those releases or request publication to advance or finish this
source sprint. Record the known independent-module limitation and continue.

Unavailable optional shell prerequisites or race-detector support are evidence
limitations, not stage gates. Run the available checks, record what could not
run, and continue. Deterministic regression checks remain required; failures in
supported checks require investigation and in-scope correction. Revisit checks
deferred for internal dependencies before the final report. A genuine inability
to run required final verification must be reported as incomplete verification,
not converted into a passed check or a request for per-stage approval.

## Stage 1 — Retain aggregate smoke cancellation

**Complete.** The progress-delivery cancellation regression reproduced both
the false success and missing joined cause before the fix. The focused aligned
workspace checks passed: `go test -mod=readonly -run 'TestSmokeAggregate|TestSmokeTestCancellation' ./integrations/ckprompt`
with Go 1.27.0, `GOTOOLCHAIN=local`, and `GOPROXY=off`. Tests cover partial
results with and without a provider error, retained diagnostics and explanation,
omitted callbacks, and cancellation after the final check.

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

**Complete.** Both captured binding replay and aggregate request seed creation
copy nested JSON objects and arrays. The two new boundary regressions failed
against the original implementation; focused request-flag and aggregate tests
passed in the aligned workspace with Go 1.27.0, `GOTOOLCHAIN=local`,
`GOPROXY=off`, and `-mod=readonly`. Nil, empty, integer and decimal values are
covered.

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

**Complete.** Finalization closes deferred acceptance while detaching its
batch; completion and terminal reporting remain available. The channel-controlled
regression failed against the original code and now passes alongside focused
reporter and hidden-deferred tests, both normally and with `-race -count=1`, in
the aligned Go 1.27.0 workspace with offline, read-only module resolution. The
old reporter test wrappers were replaced with real selection and finalization.

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` where supported, supplementing the required deterministic
   acceptance/finalization regression. Record unavailable race support and proceed.
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

**Complete.** Missing prepared requests produce an operational failure while
retaining diagnostics and explanations. The public-command regression reproduced
the original successful null preview; focused preparation tests now pass in the
offline aligned workspace with Go 1.27.0 and read-only module resolution, covering
valid results, provider errors, and cancellation as well.

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

**Complete.** Buffered show preparation carries cancellation outside managed
rendering without emitting the incomplete report. The two-scope regression
failed against the original behavior and now passes, including simultaneous
native rendering failure; focused show, buffered cancellation and write-failure
tests passed in the offline aligned Go 1.27.0 workspace with `-mod=readonly`.

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

**Complete.** The fixture generates Bash, Zsh and Fish scripts; the available
interactive Bash backend and consumer checks passed. The full opt-in commands
reported failures for Zsh and Fish because those shells are not installed;
their interactive behavior remains unverified. The core example's bare and
explicit `demo` invocations succeeded, and an invalid scenario returned usage
status 2. Checks used Go 1.27.0 with offline, read-only module resolution.

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

**Complete.** Finalization clears both borrowed writer references after
capturing presentation, without closing them. Tests cover success, operational
failure, cancellation, late handles and writer ownership; focused reporter tests
pass in the offline aligned Go 1.27.0 workspace with `-mod=readonly`.

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

**Complete.** Terminal and ordinary reporting share detail-rendering and error
classification under the existing lock. Focused reporter and hidden-deferred
tests passed in the offline aligned Go 1.27.0 workspace with `-mod=readonly`.

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

**Complete.** Provider and YAML conversion GoDoc now describe the current
handoff; `ExplanationReader` only acquires evidence. Focused core YAML conversion
and ckconfig show, explanation, adapter and delivery tests passed in the offline
aligned Go 1.27.0 workspace with `-mod=readonly`, including a custom Explain-only
provider for path show and all explanation formats.

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 where supported for the final reporting
   changes, recording unavailable support. 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.