Record flag consumption decision and joint alias analysis

docs/roadmap/audit/catalog.md

@@ -273,9 +273,17 @@ 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.
 
-Share a small neutral token-consumption primitive. Keep execution normalization,
+**Decision:** share a small flag-consumption operation through the existing
-failure provenance, and partial-word completion policies in their existing
+neutral internal helpers. Share facts about flag identity, attached versus
-owners rather than introducing a common public parser.
+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).
 

docs/roadmap/audit/remediation-analysis.md

@@ -8,7 +8,7 @@ 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–F15, and F21 remain selected. In
+Existing catalog decisions for F03, F10, F11, F13–F16, and 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.
@@ -18,8 +18,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? | Callers compared; recommendation pending agreement |
+| 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? | Joint design pending; remediation selected |
+| 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 |
 
 ## F10 — Flag declaration naming
@@ -186,7 +186,9 @@ paths, preserving explicit empties, short clusters, and entered spelling.
 If a proposed extraction needs extensive caller-specific controls, narrow it
 and retain the remaining duplication rather than forcing complete unification.
 
-**Decision:** recommendation pending agreement; no refactor is implemented.
+**Decision:** the recommended internal sharing boundary is accepted and recorded
+in the catalog. Execution and completion retain their separate policies; exact
+private signatures remain implementation choices. No refactor is implemented.
 
 ## F14–F15 — Joint source-prefix design
 
@@ -200,12 +202,47 @@ and [F15](catalog.md#f15--p3-alias-help-scans-the-entire-source-catalog-for-each
 alias source structure, or one shared private index if the existing structure
 cannot serve both operations simply.
 
-**Preliminary recommendation:** prefer reuse; preserve classification,
+**Analysis:** the existing [alias resolver](../../../internal/alias/resolver.go)
-authoritative resolution, deduplication, and ordering. Select the concrete
+already builds a source-path tree. Each node represents one distinct prefix,
-traversal and ownership together. No performance test is required to justify
+has child links, and identifies whether a mapping ends there. Shared source
-remediation; correctness validation remains appropriate.
+prefixes therefore already have a single structural representation.
 
-**Decision:** joint remediation selected in the catalog; concrete design pending.
+F14's `discoverFlagContexts` in [flag_aliases.go](../../../flag_aliases.go)
+instead walks each declaration independently, repeatedly copying and classifying
+common prefixes before deduplicating accepted results. F15's `routeHelpAliases`
+in [help_view.go](../../../help_view.go) scans the full alias catalog at every
+intermediate rewrite path, even when that prefix has no descendants.
+
+For example, sources `legacy team show` and `legacy team check` share `legacy`
+and `legacy team`. Setup can examine each shared prefix once. Help at
+`legacy team` can find its descendants through that tree branch without scanning
+unrelated source paths.
+
+**Recommendation:** add narrow internal read-only operations on the existing
+resolver tree for these two needs:
+
+1. Enumerate each distinct nonempty proper source prefix once for F14. Apply
+   the existing discovery classification once per candidate, retaining exclusions
+   for canonical paths, exact alias sources, and valid canonical operand space.
+2. Find strictly descendant alias sources beneath a supplied prefix for F15.
+   Continue visiting the existing intermediate resolution paths. Resolve each
+   composed entered path through the authoritative resolver, then retain current
+   canonical-target checks, suffix deduplication, and output sorting.
+
+Keep trie nodes private and preserve captured path ownership. Reuse the tree's
+existing routing-snapshot lifetime rather than creating a parallel index or a
+cross-invocation result cache. Root help can continue using the complete catalog
+when it actually needs all entries. No public API or routing grammar change is
+needed; internal method names and return shapes remain implementation choices.
+
+This removes the identified repeated scans and preparation, without claiming
+that all routing or installation costs become linear. Test the preserved
+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.
 
 ## F17–F20 — Proportionate private extractions