535 lines
30 KiB
Markdown
535 lines
30 KiB
Markdown
# Consolidated audit catalog
|
||
|
||
Status: **13 distinct open findings: 13 P3**, consolidated from 30
|
||
numbered entries in seven audit documents. Reviewed audit state:
|
||
`db732e3a1de55c844f77870e1c6db683c2685d5d`.
|
||
|
||
This catalog owns grouping, recommended review order, and subsequent remediation
|
||
decisions. The linked original entries retain code locations, evidence,
|
||
contract analysis, and detailed
|
||
remediation options. Consolidation alone does not resolve a finding or select a
|
||
proposed contract change. Explicit decisions recorded below supersede the
|
||
original entries' alternatives; findings remain open until remediated.
|
||
Original priorities are retained. Within those priorities, incorrect outcomes
|
||
and request isolation lead; blocked validation,
|
||
resource retention, and consumer contracts precede scaling and maintainability
|
||
work; editorial and historical navigation issues follow.
|
||
|
||
The [remediation analysis](remediation-analysis.md) records the completed design
|
||
review and its rationale. All choices identified for discussion have been
|
||
resolved; no further product or architectural decision is required before
|
||
implementation planning. Accepted conclusions are recorded in this catalog;
|
||
the remaining findings still require remediation and validation.
|
||
|
||
Three pairs describe the same underlying issue: correctness C2/concurrency N2,
|
||
correctness C4/concurrency N3, and complexity M6/responsibility R1. Other
|
||
related findings remain distinct where they concern different failure modes or
|
||
changes. Documentation cross-references and the responsibility review's closing
|
||
assessment are supporting discussion, not additional numbered findings.
|
||
|
||
The [internal overview](../../internal/overview.md) inventories the
|
||
architecture: core owns declarations, routing, typed input preparation,
|
||
dispatch, completion, and reporting; neutral private packages isolate the
|
||
Cobra/pflag adapter. ckconfig and ckprompt adapt native upstream capabilities
|
||
through separate optional modules. Applications retain loaders, builders,
|
||
runtime resources, and executable lifecycle; release launchers delegate to
|
||
ReleaseKit. The findings call for specific fixes and simplifications within
|
||
these boundaries.
|
||
|
||
## F01 — P2: Aggregate smoke testing can stop on cancellation and return success
|
||
|
||
**Complete.** The later cancellation checkpoint retains a cause when work is
|
||
omitted, without duplicating a cause already recorded. Focused aggregate and
|
||
cancellation tests pass in the aligned workspace; the new progress-delivery
|
||
regression failed against the original behavior for both successful and failed
|
||
provider calls, and also covers cancellation after the last completed check.
|
||
|
||
In ckprompt's `runSmokeAggregate`, cancellation triggered during progress
|
||
delivery can stop the remaining smoke kinds without entering the operation
|
||
cause. A partial aggregate can consequently return status 0; cancellation can
|
||
also be omitted when another error already exists.
|
||
|
||
Record cancellation at the checkpoint that actually omits remaining work,
|
||
preserving acquired reports and prior errors. This does not require treating
|
||
cancellation after all requested work has completed as a failure.
|
||
|
||
**Original:** [04-concurrency N1](04-concurrency.md#n1--p2-cancellation-can-stop-aggregate-smoke-testing-with-a-success-outcome).
|
||
Also noted in the [documentation cross-references](13-documentation.md#previously-recorded-discrepancies-affecting-documented-behavior).
|
||
|
||
## F02 — P2: CLI provider parameters share mutable state across requests
|
||
|
||
**Complete.** CLI JSON is copied at captured binding application and each
|
||
aggregate seed boundary. Both regressions failed before the fix and focused
|
||
aligned-workspace tests passed, including nested objects and arrays, nil and
|
||
empty values, and numeric types.
|
||
|
||
ckprompt assigns parsed `ExtraParams` maps directly to request destinations, and
|
||
smoke seeds share those nested maps. Mutation by one callback can change later
|
||
smoke requests or another destination receiving the same captured bindings.
|
||
|
||
Clone the CLI-owned JSON maps and arrays at binding application and seed
|
||
creation. Preserve presence and numeric semantics, and application builders'
|
||
authority; a general deep-copy framework is unnecessary.
|
||
|
||
**Original:** [01-correctness C1](01-correctness.md#c1--p2-cli-provider-parameter-objects-leak-mutations-between-requests).
|
||
Also noted in the [documentation cross-references](13-documentation.md#previously-recorded-discrepancies-affecting-documented-behavior).
|
||
|
||
## F03 — P2: Finalization can discard an accepted deferred message
|
||
|
||
**Complete.** The acceptance cutoff and batch detachment now share one locked
|
||
transition. A deterministic regression reproduces the former lost submission and
|
||
checks late empty/hidden submissions, accepted delivery, completion, and terminal
|
||
ordering. Focused reporter tests passed normally and under the race detector;
|
||
existing tests cover visibility and presentation failures.
|
||
|
||
Core reporter finalization detaches the deferred batch before closing
|
||
acceptance. A concurrent submission can return success while presentation is in
|
||
progress, then be discarded when finalization clears the queue. The returned
|
||
delivery evidence can still indicate success.
|
||
|
||
**Decision:** atomically close deferred-message acceptance when finalization
|
||
begins, deliver the already accepted batch under the existing presentation rules,
|
||
and return `ErrReporterClosed` for later deferred submissions. Preserve the
|
||
finalizer's own delivery path and document the acceptance cutoff. Repeatedly
|
||
draining newly arriving submissions is not selected; completion must not depend
|
||
on application producers eventually stopping. This does not add responsibility
|
||
for application goroutines or change ordinary message visibility.
|
||
|
||
The two source entries describe the same logical ordering defect, rather than a
|
||
data race.
|
||
|
||
**Originals:** [01-correctness C2](01-correctness.md#c2--p2-finalization-can-discard-a-successfully-queued-deferred-message);
|
||
[04-concurrency N2](04-concurrency.md#n2--p2-deferred-message-acceptance-remains-open-after-the-final-batch-detaches).
|
||
Also noted in the [documentation cross-references](13-documentation.md#previously-recorded-discrepancies-affecting-documented-behavior).
|
||
|
||
## F04 — P2: Prepared-request preview can succeed without a prepared result
|
||
|
||
**Complete.** The command rejects a missing prepared request after provider and
|
||
cancellation checks, preserving acquired evidence. Its public-command regression
|
||
failed against the original behavior; focused preparation tests pass with valid,
|
||
missing, provider-error and canceled acquisitions.
|
||
|
||
The ckprompt prepared-request handler accepts an empty `Acquired` value with a
|
||
nil error from `PrepareRequest`. It renders `null` and reports success despite
|
||
having no prepared request.
|
||
|
||
Reject the missing result as an operational failure in this handler while
|
||
preserving diagnostics and explanations. Keep core's general ability to render a
|
||
legitimate null report.
|
||
|
||
**Original:** [01-correctness C3](01-correctness.md#c3--p2-prepared-request-inspection-reports-success-without-a-result).
|
||
Also noted in the [documentation cross-references](13-documentation.md#previously-recorded-discrepancies-affecting-documented-behavior).
|
||
|
||
## F05 — P2: Configuration-show cancellation is also recorded as a rendering failure
|
||
|
||
**Complete.** A cancellation checkpoint stops buffered show preparation without
|
||
reporting cancellation as a render error. A regression failed before the fix;
|
||
focused tests now verify no partial output, cancellation identity, and retained
|
||
native rendering errors when both occur.
|
||
|
||
ckconfig checks cancellation during buffered show preparation inside the
|
||
`RenderOutput` callback. Returning that cancellation from the renderer records
|
||
both the correct operation cause and a false presentation failure, conflating
|
||
two established outcome dimensions.
|
||
|
||
Carry preparation cancellation separately from renderer errors while retaining
|
||
genuine rendering and writing failures and avoiding partial aggregate output.
|
||
Both audits identify the same classification defect.
|
||
|
||
**Originals:** [01-correctness C4](01-correctness.md#c4--p2-show-preparation-labels-ordinary-cancellation-as-a-rendering-error);
|
||
[04-concurrency N3](04-concurrency.md#n3--p2-buffered-configuration-show-cancellation-becomes-a-presentation-failure).
|
||
Also noted in the [documentation cross-references](13-documentation.md#previously-recorded-discrepancies-affecting-documented-behavior).
|
||
|
||
## F06 — P3: The optional interactive completion consumer fails before shell validation
|
||
|
||
**Complete.** The renamed application-owned choice flag permits script
|
||
generation and the Bash interactive consumer and backend checks pass. Zsh and
|
||
Fish interactive checks remain unavailable because those shells are not installed.
|
||
|
||
The completion consumer fixture declares the reserved `format` flag, so App
|
||
construction fails before it can generate scripts or exercise interactive
|
||
completion. Default test suites skip this optional path.
|
||
|
||
Use core's format flag or rename the fixture's custom flag, update its
|
||
expectations, and rerun available shell checks. The fixture failure does not
|
||
establish a defect in generated completion scripts.
|
||
|
||
**Original:** [01-correctness C6](01-correctness.md#c6--p3-the-interactive-completion-consumer-cannot-construct-its-app).
|
||
Also noted in the [documentation cross-references](13-documentation.md#previously-recorded-discrepancies-affecting-documented-behavior).
|
||
|
||
## F07 — P3: Closed reporting handles retain both borrowed destinations
|
||
|
||
**Complete.** Finalization drops direct destination references after presentation
|
||
is captured. Focused reporter tests cover successful, failed and canceled outcomes,
|
||
closed handles, retained causes, and caller ownership.
|
||
|
||
A retained closed `Reporter`, `Output`, or `DeferredReporter` keeps the shared
|
||
reporting state and both destination writers reachable. Applications retaining a
|
||
closed handle can therefore retain large buffers or resource-bearing writer
|
||
objects after invocation completion.
|
||
|
||
Clear direct borrowed-writer references after final presentation under the
|
||
reporting lock, preserving closed-handle behavior and returned error evidence.
|
||
Do not close or flush application-owned writers. This is conditional retention
|
||
through a reachable handle, not an unreachable heap leak.
|
||
|
||
**Original:** [05-resources RM1](05-resources.md#rm1--p3-closed-reporting-handles-retain-both-destination-objects).
|
||
|
||
## F08 — P3: The core example overwrites its optional argument default
|
||
|
||
**Complete.** The example assigns a scenario only when supplied; bare and
|
||
explicit demo invocations succeed and an invalid scenario returns usage status 2.
|
||
|
||
The example's scenario setter replaces the factory's `"demo"` default with an
|
||
unsupplied empty value. The ordinary `report` invocation consequently fails with
|
||
a usage error.
|
||
|
||
Assign the optional argument only when its supplied state is set. Fix the
|
||
consumer without changing core's optional-binding semantics.
|
||
|
||
**Original:** [01-correctness C5](01-correctness.md#c5--p3-the-core-example-overwrites-its-optional-scenario-default).
|
||
|
||
## F09 — P3: The configuration provider contract omits its required YAML representation
|
||
|
||
**Complete.** EffectiveWriter, View and DecodeYAMLReport GoDoc describe the
|
||
actual single-document conversion boundary; focused conversion and show tests pass.
|
||
|
||
`EffectiveWriter` GoDoc promises a native representation but omits that `config
|
||
show` converts one supported YAML document through `DecodeYAMLReport`. Custom
|
||
providers can supply output that appears compatible with the description yet
|
||
fails conversion; native formatting is not passed through.
|
||
|
||
Document that boundary with the public interface and conversion helper, and
|
||
update `View`'s report description. This clarification is independent of the
|
||
unused explanation-writer requirement in F11.
|
||
|
||
**Original:** [13-documentation D1](13-documentation.md#d1--p3-configuration-provider-godoc-omits-the-effective-output-contract).
|
||
|
||
## F10 — P3: Public flag metadata omits enforced naming and reserved-spelling rules
|
||
|
||
**Complete.** FlagMeta documents the existing declaration rules and related
|
||
rename and alias GoDoc refers to them. The prose was checked against the
|
||
installation validator; no runtime rule changed.
|
||
|
||
`FlagMeta` describes names without leading dashes and an optional short
|
||
spelling, while installation enforces additional name grammar and reserved
|
||
spellings. Consumers must discover those constraints through errors or private
|
||
implementation.
|
||
|
||
**Decision:** retain and document the existing declaration rules. Long names use
|
||
Unicode lowercase letters and digits separated by single hyphens; numeric names
|
||
and names beginning with digits remain allowed. Keep core-owned reserved names
|
||
and the optional one-byte short-spelling rules, excluding `-` and reserved `h`.
|
||
Do not add ASCII-only or leading-letter restrictions, or automatic rewriting of
|
||
invalid names. These rules concern flag names, not supplied values.
|
||
|
||
Document the rules once with `FlagMeta` and link related public helpers. This
|
||
remediation changes documentation, not runtime validation.
|
||
|
||
The [F10 analysis](remediation-analysis.md#f10--flag-declaration-naming) reviews
|
||
the naming convention's basis and records the accepted direction.
|
||
|
||
**Original:** [13-documentation D2](13-documentation.md#d2--p3-public-flag-metadata-omits-enforced-declaration-constraints).
|
||
|
||
## F11 — P3: Explanation providers must implement an unused text writer
|
||
|
||
**Complete.** The interface now requires only Explain; focused tests exercise an
|
||
Explain-only provider for focused show and explanations across formats, including
|
||
delivery failures. Obsolete writer stubs and the interface-writer assertion were removed.
|
||
|
||
`ExplanationReader` still requires `WriteExplanation` even though production
|
||
show/explain handlers acquire evidence with `Explain` and core renders it. This
|
||
burdens custom providers and suggests a presentation responsibility that
|
||
standard commands no longer use.
|
||
|
||
**Decision:** remove `WriteExplanation` from `ExplanationReader`, leaving the
|
||
acquisition responsibility, and update GoDoc, writer-only stubs, and assertions.
|
||
Native provider objects may retain their own rendering methods. Do not add
|
||
compatibility scaffolding or restore provider-owned rendering to justify the
|
||
unused requirement. Both audits identify the same obsolete requirement.
|
||
|
||
The interface change removes the ability to invoke that method through
|
||
`View.Explanation`. CommandKit is still pre-release with no consumers, so no
|
||
consumer compatibility or migration work is needed.
|
||
|
||
**Originals:** [03-complexity M6](03-complexity.md#m6--p3-explanation-providers-must-implement-an-unused-rendering-capability);
|
||
[A1-responsibility R1](A1-responsibility.md#r1--p3-explanation-providers-still-owe-an-unused-text-writer).
|
||
|
||
## F12 — P3: Parser sessions carry unused execution resources
|
||
|
||
**Complete.** Unused execution and parser resource plumbing was removed; the
|
||
backend retains discard destinations and buffered help. Focused routing, help,
|
||
context-forwarding and session-isolation tests passed.
|
||
|
||
Core and the Cobra adapter duplicate stream normalization and retain context and
|
||
streams through parser options and backend nodes, although the adapter parses
|
||
and renders buffered help rather than executing callbacks or reading application
|
||
input. The execution object also retains an unread streams field.
|
||
|
||
Remove unused resource plumbing while preserving real invocation resources and
|
||
explicit internal discard destinations/local help buffers. This simplifies
|
||
ownership; it is separate from the closed-reporting-handle retention in F07.
|
||
|
||
**Original:** [A1-responsibility R2](A1-responsibility.md#r2--p3-parser-sessions-carry-application-execution-resources-they-do-not-use).
|
||
|
||
## F13 — P3: Flag-alias compilation repeatedly walks shared chain suffixes
|
||
|
||
For A chained effective flag mappings across C contexts, independent target
|
||
walks can perform Θ(CA²) target examinations, including inactive chains. Each
|
||
source repeats work already performed for another source's suffix.
|
||
|
||
Use context-local visitation states and memoized terminal results. Traversal can
|
||
become expected O(A) per context, with existing deterministic sorting retaining
|
||
O(A log A) total work for these steps. Preserve scoped precedence, canonical
|
||
endpoints, missing-target behavior, and cycle diagnostics.
|
||
|
||
**Decision for F13–F15:** the repeated-work and scaling analysis sufficiently
|
||
justifies remediation. Performance testing is not a prerequisite for selecting
|
||
or implementing these changes. Validate correctness and preservation of the
|
||
selected routing and discovery semantics.
|
||
|
||
**Original:** [02-efficiency E1](02-efficiency.md#e1--p3-flag-alias-compilation-repeatedly-resolves-shared-chain-suffixes).
|
||
|
||
## F14 — P3: Discovery-context preparation repeatedly rebuilds shared prefixes
|
||
|
||
R alias sources sharing a depth-D proper prefix cause Θ(RD²) copying and key
|
||
construction before result deduplication, with repeated classification as well.
|
||
The source declarations contain only Θ(RD) tokens.
|
||
|
||
Traverse distinct source prefixes once and classify each once. For the audited
|
||
shape, this phase can become O(RD + D²).
|
||
|
||
**Decision:** implement F14 and F15 together using the existing alias resolver's
|
||
source-path tree. Add narrow internal read-only operations to enumerate distinct
|
||
nonempty proper prefixes for F14 and find strictly descendant alias sources for
|
||
F15. Retain the existing discovery classification and exclusions, applying them
|
||
once per candidate prefix.
|
||
|
||
Reuse the tree's routing-snapshot lifetime; do not introduce a parallel index or
|
||
a cross-invocation result cache. The repeated preparation and help-time scan
|
||
remain distinct findings. The [joint analysis](remediation-analysis.md#f14f15--joint-source-prefix-design)
|
||
records the accepted design. The performance-testing decision under F13 applies
|
||
to both; implementation remains pending.
|
||
|
||
**Original:** [02-efficiency E3](02-efficiency.md#e3--p3-discovery-context-preparation-rebuilds-shared-prefixes-repeatedly).
|
||
|
||
## F15 — P3: Alias help scans the entire source catalog for each intermediate route
|
||
|
||
Help discovery examines all A alias sources at each of P rewrite paths, doing PA
|
||
examinations and repeated copies even when there are no descendants. A valid
|
||
single-token alias chain produces Θ(A²) work to discover an empty alias section
|
||
on every such help request.
|
||
|
||
**Decision:** query the existing resolver tree for strict descendants through
|
||
the internal operation shared with F14's design. Continue visiting intermediate
|
||
resolution paths, resolving composed entered paths through the existing
|
||
resolver, and retaining canonical-target checks, suffix deduplication, and
|
||
output sorting. Root help may retain the complete catalog when all entries are
|
||
needed. No public API or CLI behavior change is selected.
|
||
|
||
The identified discovery work becomes O(A) for that example; general cases still pay for
|
||
matching candidates, resolution, and output sorting. Design this together with
|
||
F14 under the decisions recorded there and in F13.
|
||
|
||
**Original:** [02-efficiency E2](02-efficiency.md#e2--p3-alias-help-scans-every-source-for-every-intermediate-route).
|
||
|
||
## F16 — P3: Parsing and completion duplicate flag-consumption grammar
|
||
|
||
Execution parsing and completion separately implement short clusters,
|
||
attached/next values, boolean assignments, terminators, and unknown spellings.
|
||
Shared classification helpers cover only part of the grammar, leaving changes to
|
||
cross the core/backend boundary.
|
||
|
||
**Decision:** share a small flag-consumption operation through the existing
|
||
neutral internal helpers. Share facts about flag identity, attached versus
|
||
missing values, consumption of the next argument, and short-cluster position.
|
||
Keep execution normalization, failure provenance, and partial-word completion
|
||
policies in their existing owners. Preserve explicitly empty values and current
|
||
CLI behavior; no public parser or replacement backend is selected.
|
||
|
||
Retain caller-specific branches where combining them would require extensive
|
||
modes or special cases. Repair F06's completion fixture before validating this
|
||
refactor. The [F16 analysis](remediation-analysis.md#f16--shared-flag-consumption)
|
||
records the accepted boundary; implementation remains pending.
|
||
|
||
**Original:** [03-complexity M3](03-complexity.md#m3--p3-parsing-and-completion-maintain-parallel-flag-consumption-logic).
|
||
|
||
## F17 — P3: Configuration scope capture combines several compilation phases
|
||
|
||
ckconfig's `captureSuite` interleaves scope and selector capture, validation,
|
||
comparison-binding renaming, binding attachment, operation unions, and discovery
|
||
inventory. Several partially populated collections must be understood together.
|
||
|
||
**Decision:** extract cohesive scope capture/validation and selector attachment
|
||
responsibilities, and make operation bindings and discovery inventory
|
||
construction explicit. Use existing prepared types and keep related loops
|
||
together. Preserve retained error order, declaration ownership, scope and binding
|
||
identity, and metadata-only construction. Do not create new intermediate records
|
||
or a helper for each loop merely to shorten the function.
|
||
|
||
**Original:** [03-complexity M1](03-complexity.md#m1--p3-scope-capture-combines-several-compilation-phases).
|
||
|
||
## F18 — P3: Configuration preflight interleaves shared and operation-specific rules
|
||
|
||
The configuration command builder and `prepareConfigOperation` mix flag
|
||
combinations, help selection, capabilities, pointer parsing, plan assembly,
|
||
ordinary inputs, and independent comparison inputs. Understanding one operation
|
||
requires reasoning through irrelevant submodes.
|
||
|
||
**Decision:** separate operation-specific option checks, shared scope/capability
|
||
selection, and comparison input preparation with small private functions. Keep
|
||
the overall sequence explicit, including explain's help path, aggregate checks
|
||
before input construction, independent comparison sides, and input checks before
|
||
shared state creation and acquisition. Extract flag groups where this clarifies
|
||
their purpose; no generic operation engine or rule registry is selected.
|
||
|
||
**Original:** [03-complexity M2](03-complexity.md#m2--p3-configuration-preflight-mixes-shared-and-operation-specific-rules).
|
||
|
||
## F19 — P3: Typed input preparation mixes conversion, provenance, and replay assembly
|
||
|
||
`prepareInputWithOccurrences` handles shape validation, conversion-error
|
||
spelling, occurrence identities, application order, required flags, operands,
|
||
and prepared callbacks. Captured binding replay depends on those shared
|
||
identities across another code path.
|
||
|
||
**Decision:** make small extractions for conversion-error attribution and operand
|
||
preparation. Keep flag preparation, occurrence identity, and order reconstruction
|
||
together; that block may remain in the orchestration function if extraction
|
||
requires excessive plumbing. Retain dense reconstruction, the captured-replay
|
||
heap merge, binding identity, supplied-state distinctions, conversion before
|
||
input factories, and error identity. No new state containers or replay framework
|
||
are selected.
|
||
|
||
**Original:** [03-complexity M4](03-complexity.md#m4--p3-typed-preparation-combines-conversion-provenance-and-replay-assembly).
|
||
|
||
## F20 — P3: Reporter message paths duplicate detail-rendering bookkeeping
|
||
|
||
**Complete.** Both message paths share detail callback and error bookkeeping;
|
||
focused reporter tests cover visibility, ordering, closed handles, and joined
|
||
render/write evidence.
|
||
|
||
Terminal and ordinary message paths repeat callback invocation, managed-writer
|
||
setup, render-versus-write error classification, and first-error retention.
|
||
Maintaining the same presentation policy in two branches increases the chance of
|
||
drift.
|
||
|
||
**Decision:** extract one private detail-rendering helper under the existing
|
||
reporting lock, returning rendering and writing errors separately. Callers retain
|
||
visibility/discard selection, headings, delivery observations, and terminal
|
||
timing. Preserve callback order, hidden-detail execution, sticky writer failures,
|
||
and non-reentrancy; add no locks or interchangeable rendering machinery.
|
||
|
||
Keep this refactor separately reviewable from F03 and F07; it does not itself
|
||
fix deferred-message loss or writer retention. After correctness repairs, favor
|
||
F20, then F18 and F17, while keeping F19 modest. All four use private functions
|
||
and existing types, with no intended public API or CLI behavior change. The
|
||
[F17–F20 analysis](remediation-analysis.md#f17f20--proportionate-private-extractions)
|
||
records the accepted scope.
|
||
|
||
**Original:** [03-complexity M7](03-complexity.md#m7--p3-terminal-and-ordinary-messages-duplicate-detail-rendering-mechanics).
|
||
|
||
## F21 — P3: Both integrations maintain the same ConfigKit diagnostic adaptation
|
||
|
||
**Complete.** Both integrations use `ckconfig.AdaptDiagnostics`; focused
|
||
workspace adapter, acquisition and comparison tests pass, including captured
|
||
locations, severity grouping, side labels and deferred writer failures. ckprompt's
|
||
independent check against released ckconfig v0.4.0 remains blocked on release
|
||
alignment because that version lacks the helper.
|
||
|
||
ckconfig and ckprompt independently snapshot ConfigKit diagnostic evidence,
|
||
partition severities, construct detail callbacks, label sources, and delegate
|
||
native text formatting. Related Reporter scheduling switches are duplicated too.
|
||
|
||
**Decision:** expose one narrow public ckconfig diagnostic adaptation helper
|
||
and use it in both integrations. Reuse the existing private helper's shape:
|
||
accept a caller-supplied heading, native sources, and native diagnostic records;
|
||
return existing core diagnostics and an explanation ready for CLI reporting.
|
||
Preserve evidence snapshots, severity treatment, ordering within each group,
|
||
source labels, and delegation to ConfigKit's native formatter.
|
||
|
||
Callers retain operation-specific context, outcomes, error causes, and message
|
||
scheduling. Core retains visibility and delivery. Leave the smaller scheduling
|
||
switches with their callers; no additional public scheduling API or general
|
||
diagnostics framework is selected. ckprompt already depends on ckconfig, so no
|
||
new module dependency is needed.
|
||
|
||
CommandKit is pre-release with no consumers; compatibility and migration are
|
||
not constraints. The [F21 analysis](remediation-analysis.md#f21--shared-configkit-diagnostic-adaptation)
|
||
records the accepted scope and illustrative signature.
|
||
|
||
**Original:** [03-complexity M5](03-complexity.md#m5--p3-configuration-diagnostic-adaptation-is-maintained-in-both-integrations).
|
||
Also discussed in the [responsibility assessment](A1-responsibility.md#machinery-worth-retaining-under-the-selected-contracts).
|
||
|
||
## F22 — P3: Successful declaration validation eagerly formats every full path
|
||
|
||
`collectDeclarationIssues` copies and formats each ancestral path before knowing
|
||
whether a diagnostic is needed. A valid depth-N declaration chain incurs Θ(N²)
|
||
cumulative path work and allocation while producing no errors.
|
||
|
||
Use an append/truncate scratch path and format only emitted diagnostics. The
|
||
successful validation walk can become O(N) with O(D) path storage. Other
|
||
installation phases retain their own costs; this is not a claim that all App
|
||
construction becomes linear.
|
||
|
||
**Original:** [02-efficiency E4](02-efficiency.md#e4--p3-successful-declaration-validation-eagerly-constructs-every-full-path).
|
||
|
||
## F23 — P3: Concise diff rendering validates already-valid native paths
|
||
|
||
ckconfig's private pointer decoder validates arbitrary strings even though its
|
||
sole production caller supplies the canonical string of an immutable ConfigKit
|
||
`Path`. Tests sustain malformed-input branches that this boundary cannot reach.
|
||
|
||
Accept the native path directly and retain only the key-token decoding needed by
|
||
the selected concise report. Decode escapes once so `~01` remains `~1`; preserve
|
||
snapshot errors and operator-input validation.
|
||
|
||
**Original:** [A1-responsibility R3](A1-responsibility.md#r3--p3-concise-diff-rendering-revalidates-native-configkit-paths).
|
||
|
||
## F24 — P3: Obsolete private production entry points remain for tests alone
|
||
|
||
Legacy reporter setters/close, `App.parse`, and typed-preparation wrappers have
|
||
only test callers, while production uses current selection, finalization,
|
||
routed-session, and occurrence-aware paths. Some tests therefore exercise
|
||
superseded lifecycle entry points.
|
||
|
||
Move tests to the real private paths and remove obsolete production wrappers.
|
||
Keep any concise setup helpers in `_test.go` files, retaining useful behavioral
|
||
assertions without new exported test hooks.
|
||
|
||
**Original:** [A1-responsibility R4](A1-responsibility.md#r4--p3-private-production-entry-points-exist-only-to-sustain-older-tests).
|
||
|
||
## F25 — P3: The reporting ADR mixes implemented status with stale planning language
|
||
|
||
ADR 0006 marks shared reporting implemented but still directs implementation
|
||
status and format choices to a retired roadmap and describes the extension as
|
||
planned. Readers can mistake completed work for a pending prerequisite.
|
||
|
||
Clarify historical wording and link current behavior to GoDoc and the CLI
|
||
reference. Preserve the accepted architectural decision; an unchanged decision
|
||
does not need a replacement ADR.
|
||
|
||
**Original:** [13-documentation D3](13-documentation.md#d3--p3-reporting-adr-still-directs-readers-to-a-planned-implementation).
|
||
|
||
## F26 — P3: The README duplicates volatile module compatibility guidance
|
||
|
||
The root README repeats exact version combinations and candidate dependency
|
||
details already maintained by the consumer guide. The facts currently agree, but
|
||
two owners create policy and maintenance drift risk.
|
||
|
||
Keep a brief status/module overview in README and link the consumer guide for
|
||
exact compatibility and installation choices. This is documentation
|
||
consolidation, not a dependency change.
|
||
|
||
**Original:** [13-documentation D5](13-documentation.md#d5--p3-the-root-readme-duplicates-the-compatibility-matrix).
|
||
|
||
## F27 — P3: A historical release note points to a nonexistent section
|
||
|
||
The ckprompt v0.2.0 release note uses the wrong consumer-guide fragment at its
|
||
immutable tag. The file exists, but the requested section does not.
|
||
|
||
Provide the correct pinned section link in a useful forward-only correction or
|
||
erratum. Preserve the published tag, historical note, and hosted release
|
||
contents; republishing is unnecessary.
|
||
|
||
**Original:** [13-documentation D4](13-documentation.md#d4--p3-a-historical-release-note-links-to-a-nonexistent-section).
|