Finalize audit remediation decisions for implementation planning

docs/roadmap/audit/catalog.md

@@ -15,9 +15,11 @@ 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) tracks unresolved choices
+The [remediation analysis](remediation-analysis.md) records the completed design
-and recommendations for sequential discussion. Accepted conclusions are recorded
+review and its rationale. All choices identified for discussion have been
-in this catalog; analysis alone does not select a remedy.
+resolved; no further product or architectural decision is required before
+implementation planning. Accepted conclusions are recorded in this catalog;
+all 27 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
@@ -306,9 +308,12 @@ 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.
 
-Extract cohesive private phases over the existing prepared types, keeping
+**Decision:** extract cohesive scope capture/validation and selector attachment
-related loops together. Preserve retained error order, declaration ownership,
+responsibilities, and make operation bindings and discovery inventory
-scope and binding identity, and metadata-only construction.
+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).
 
@@ -319,10 +324,12 @@ combinations, help selection, capabilities, pointer parsing, plan assembly,
 ordinary inputs, and independent comparison inputs. Understanding one operation
 requires reasoning through irrelevant submodes.
 
-Separate operation options, shared selection, and comparison preparation with
+**Decision:** separate operation-specific option checks, shared scope/capability
-small private functions. Preserve the ordering of checks, input factories,
+selection, and comparison input preparation with small private functions. Keep
-binding application, state construction, and acquisition; no generic operation
+the overall sequence explicit, including explain's help path, aggregate checks
-engine is needed.
+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).
 
@@ -333,9 +340,13 @@ spelling, occurrence identities, application order, required flags, operands,
 and prepared callbacks. Captured binding replay depends on those shared
 identities across another code path.
 
-Extract cohesive error translation, flag/occurrence preparation, and argument
+**Decision:** make small extractions for conversion-error attribution and operand
-preparation. Retain the selected dense reconstruction and heap merge, binding
+preparation. Keep flag preparation, occurrence identity, and order reconstruction
-identity, conversion-before-factory ordering, and error identity.
+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).
 
@@ -346,10 +357,18 @@ setup, render-versus-write error classification, and first-error retention.
 Maintaining the same presentation policy in two branches increases the chance of
 drift.
 
-Extract a private helper under the existing reporting lock. Keep
+**Decision:** extract one private detail-rendering helper under the existing
-visibility/discard selection, headings, delivery observations, callback
+reporting lock, returning rendering and writing errors separately. Callers retain
-ordering, and non-reentrancy explicit. This refactor does not itself fix
+visibility/discard selection, headings, delivery observations, and terminal
-deferred-message loss or writer retention.
+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; implementation remains pending.
 
 **Original:** [03-complexity M7](03-complexity.md#m7--p3-terminal-and-ordinary-messages-duplicate-detail-rendering-mechanics).
 

docs/roadmap/audit/remediation-analysis.md

@@ -1,14 +1,15 @@
 # Audit remediation analysis
 
-Status: discussion in progress; no implementation changes made.
+Status: remediation decisions agreed; ready for implementation planning. No
+implementation changes made.
 
-This document owns analysis of unresolved remediation choices, in the discussion
+This document records analysis of the remediation choices reviewed in the
-order below. The [catalog](catalog.md) owns the findings, accepted remediation
+discussion order below. The [catalog](catalog.md) owns the findings, accepted remediation
 decisions, and their status. Original audits retain detailed evidence. Record
 accepted conclusions in the catalog and mark the corresponding discussion here
 decided; a decision does not close a finding before implementation.
 
-Existing catalog decisions for F03, F10, F11, F13–F16, and F21 remain selected. In
+Existing catalog decisions for F03, F10, F11, and F13–F21 remain selected. In
 particular, performance testing is not a prerequisite for F13–F15, and F14 and
 F15 are to be designed together. CommandKit is pre-release with no consumers;
 consumer compatibility and migration are not constraints on these choices.
@@ -20,7 +21,7 @@ Straightforward correctness repairs need not wait for this discussion sequence.
 | 2 | F21 | What narrow diagnostic adaptation API would simplify both integrations? | Decided: shared public ckconfig helper; remediation pending |
 | 3 | F16 | Which flag-consumption facts can parsing and completion usefully share? | Decided: shared internal mechanics, separate caller policies; remediation pending |
 | 4 | F14–F15 | How should both operations reuse source-prefix processing? | Decided: reuse existing resolver tree; remediation pending |
-| 5 | F17–F20 | Which private extractions materially simplify the existing code? | Functions reviewed; individual recommendations pending agreement |
+| 5 | F17–F20 | Which private extractions materially simplify the existing code? | Decided: bounded private extractions, conservative F19; remediation pending |
 
 ## F10 — Flag declaration naming
 
@@ -96,7 +97,7 @@ without introducing a broader diagnostics framework?
 **Evidence:** [catalog F21](catalog.md#f21--p3-both-integrations-maintain-the-same-configkit-diagnostic-adaptation)
 links both adapters and the original analysis.
 
-**Options to examine:** a narrow public ckconfig helper returning existing core
+**Options considered:** a narrow public ckconfig helper returning existing core
 diagnostics and an explanation, or retaining private implementations if the
 shared API adds more complexity than it removes.
 
@@ -147,7 +148,7 @@ completion retain their different handling of incomplete input?
 
 **Evidence:** [catalog F16](catalog.md#f16--p3-parsing-and-completion-duplicate-flag-consumption-grammar).
 
-**Options to examine:** a small neutral consumption primitive or deliberate
+**Options considered:** a small neutral consumption primitive or deliberate
 retention of duplication where a shared helper needs extensive caller modes.
 
 **Analysis:** execution's `interpretFlagTokens` in
@@ -198,7 +199,7 @@ structure without parallel indexes or changed routing semantics?
 **Evidence:** [catalog F14](catalog.md#f14--p3-discovery-context-preparation-repeatedly-rebuilds-shared-prefixes)
 and [F15](catalog.md#f15--p3-alias-help-scans-the-entire-source-catalog-for-each-intermediate-route).
 
-**Options to examine:** traversal and descendant lookup through the existing
+**Options considered:** traversal and descendant lookup through the existing
 alias source structure, or one shared private index if the existing structure
 cannot serve both operations simply.
 
@@ -257,7 +258,7 @@ adding records, phases, or configurable mechanisms merely to shorten functions?
 [F19](catalog.md#f19--p3-typed-input-preparation-mixes-conversion-provenance-and-replay-assembly),
 and [F20](catalog.md#f20--p3-reporter-message-paths-duplicate-detail-rendering-bookkeeping).
 
-**Options to examine:** cohesive functions over existing private types, or
+**Options considered:** cohesive functions over existing private types, or
 retaining related code together where extraction only adds indirection.
 
 These are maintenance improvements, not newly established incorrect CLI
@@ -347,5 +348,26 @@ each resulting diff by whether responsibilities are easier to follow and
 existing behavioral coverage still protects the selected contracts. Tests should
 not freeze new helper boundaries or incidental private call order.
 
-**Decision:** all four recommendations pending agreement; no refactoring has
+**Decision:** all four bounded extraction recommendations and the sequencing
-been implemented.
+guidance above are accepted and recorded in the catalog. F19 remains deliberately
+conservative. No refactoring has been implemented.
+
+## Readiness for implementation planning
+
+The discussion sequence is complete. No unresolved product or architectural
+choice identified in this review blocks preparation of the implementation plan.
+The catalog's 27 findings remain open until their remedies are implemented and
+validated.
+
+The plan can assign work units, dependencies, and proportionate verification.
+Routine details such as private helper signatures, the public diagnostic
+helper's final name, and the completion fixture's replacement flag are ordinary
+implementation choices within the accepted scope. Preserve the recorded
+boundaries; revisit a decision only if concrete implementation evidence exposes
+a conflict or a materially different tradeoff.
+
+Keep F14–F15 together, repair F06 before validating F16, and coordinate the
+reporter work in F03, F07, F20, and the relevant parts of F24 without obscuring
+their separate purposes. Validation should distinguish the aligned workspace
+from independent modules. No implementation plan or production changes are
+included in this analysis update.