Record alias tree decision and private refactoring analysis

docs/roadmap/audit/remediation-analysis.md

@@ -19,8 +19,8 @@ Straightforward correctness repairs need not wait for this discussion sequence.
 | 1 | F10 | Which flag declaration rules should be documented as the intended contract? | Decided: retain and document existing rules; remediation pending |
 | 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? | Existing tree inspected; reuse recommendation pending agreement |
-| 5 | F17–F20 | Which private extractions materially simplify the existing code? | Individual extraction review 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 |
 
 ## F10 — Flag declaration naming
 
@@ -241,8 +241,11 @@ discovery/help behavior, including shared prefixes, chains, longer overrides,
 and updated registration where relevant. As already decided, performance testing
 is not a prerequisite for remediation.
 
-**Decision:** joint remediation is selected in the catalog; reuse of the existing
-tree through these internal operations is recommended, pending agreement.
+**Decision:** reuse of the existing resolver tree through the two internal
+operations above is accepted and recorded in the catalog. Preserve existing
+discovery and routing semantics; no parallel index, new cache lifecycle, public
+API change, or performance-testing prerequisite is selected. Implementation
+remains pending.
 
 ## F17–F20 — Proportionate private extractions
 
@@ -257,9 +260,92 @@ and [F20](catalog.md#f20--p3-reporter-message-paths-duplicate-detail-rendering-b
 **Options to examine:** cohesive functions over existing private types, or
 retaining related code together where extraction only adds indirection.
 
-**Preliminary recommendation:** review each extraction separately. F20 has a
-concrete shared rendering/error policy; keep its refactor distinct from F03's
-correctness repair. For F17–F19, make meaningful responsibilities and required
-ordering visible without treating incidental private sequences as contracts.
+These are maintenance improvements, not newly established incorrect CLI
+outcomes. Recommendations below use existing private types and ordinary
+functions. No public API, generic pipeline, or additional validation policy is
+needed. Keep related work together; a lower function-length or complexity score
+is not itself a completion criterion.
 
-**Decision:** individual extraction choices pending review.
+### F17 — Separate configuration suite setup responsibilities
+
+**Analysis:** `captureSuite` in [family.go](../../../integrations/ckconfig/family.go)
+captures scope and selector declarations, validates provider wiring, attaches
+selectors to scopes, determines command availability, and builds discovery
+metadata. Maintaining one of those responsibilities requires understanding
+several partially populated collections.
+
+**Recommendation:** extract cohesive scope capture/validation and selector
+attachment responsibilities, then make operation bindings and discovery
+inventory construction explicit. Keep related loops together and use the
+existing prepared-suite types. Retain declaration ownership, accumulated
+errors and their order, binding identity, and metadata-only construction.
+Do not load configuration or invoke application factories during this setup.
+
+The benefit is making it clear where a new scope or selector rule belongs.
+Exact helper boundaries can follow the implementation; do not create a helper
+for each loop or new intermediate records merely to divide the function.
+
+### F18 — Separate ordinary configuration preparation from comparison
+
+**Analysis:** `prepareConfigOperation` in
+[input.go](../../../integrations/ckconfig/input.go) handles command-specific flag
+rules, scope/capability checks, path parsing, and both ordinary and two-sided
+input preparation. The command builder also mixes several operation-specific
+flag groups into its declarations.
+
+**Recommendation:** isolate operation-specific option checks, shared scope and
+capability selection, and comparison input preparation with small private
+functions. Keep an explicit orchestration function showing the actual order;
+do not replace its operation branches with a rule registry. Extract flag groups
+only where that makes their purpose clearer.
+
+Preserve bare explain's help path, aggregate capability checking before input
+construction, independent left/right comparison selections, and completion of
+input checks before shared state creation and acquisition. This makes it easier
+to change one command without reasoning through every other command's submode.
+
+### F19 — Keep input-ordering machinery together
+
+**Analysis:** `prepareInputWithOccurrences` in [binding.go](../../../binding.go)
+combines value conversion, error attribution, occurrence-position assignment,
+required checks, operand allocation, and assembly of later input setters.
+Captured binding replay relies on the same occurrence identities.
+
+**Recommendation:** start with small extractions for conversion-error
+attribution and operand preparation. Keep flag preparation, occurrence identity,
+and order reconstruction together as one coherent block; that block may remain
+in the orchestration function if moving it requires excessive plumbing.
+
+For example, a conversion error should still identify the spelling the operator
+actually used, and repeated/interleaved inputs should still apply in their
+selected order. Preserve supplied-state distinctions, original error identity,
+and conversion before application input factories run. Retain the existing
+dense reconstruction and captured-replay merge algorithms. This is the most
+conservative extraction recommendation of the four; introducing new state
+containers or a replay framework would defeat its purpose.
+
+### F20 — Share detail-rendering error bookkeeping
+
+**Analysis:** `renderTerminalLocked` and `submitMessageLocked` in
+[reporter.go](../../../reporter.go) both invoke detail callbacks through managed
+writers, distinguish rendering failures from destination write failures, and
+retain the first error of each kind. Their headings and visibility rules differ.
+
+**Recommendation:** use one private detail-rendering helper under the existing
+reporting lock, returning rendering and writing errors separately. Callers keep
+headings, visibility/discard selection, destination delivery observations, and
+terminal timing. Preserve callback order, hidden-detail execution, sticky writer
+errors, and callback non-reentrancy; add no locks or interchangeable renderers.
+
+This is the clearest duplication removal of the four. Keep it separately
+reviewable from F03's deferred-acceptance fix and F07's writer-reference release;
+it does not itself repair either defect.
+
+**Recommendation on sequencing:** correctness fixes remain first. Among these
+maintenance changes, favor F20, then F18 and F17, with F19 kept small. Evaluate
+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
+been implemented.