Record future shell completion direction for aliases

docs/roadmap/aliases.md

@@ -524,6 +524,41 @@ the operator supplied and identify the canonical flag where helpful. Conversion,
 required-value checks, and repetition behavior continue to come from the
 canonical binding.
 
+## Future shell completion
+
+The direction for future shell completion is canonical suggestions with
+alias-aware interpretation. Suggest canonical command and flag names rather
+than enumerating aliases. Resolve aliases the operator has already entered so
+completion can continue using the target's command structure and input metadata.
+
+For example, `app <TAB>` suggests canonical commands. With `pk → promptkit`,
+`app pk <TAB>` can suggest canonical children available through that route.
+After a complete command alias, use the target's flags and operands as the
+basis for completion. Recognize manually entered flag aliases when identifying
+the canonical binding whose value is being completed. Suggestions beneath a
+group alias must account for more-specific mappings so their interpretation
+agrees with execution routing.
+
+Keep validated canonical metadata and alias relationships available internally
+for metadata-only lookup independently of execution and help rendering. Future
+completion can reuse those records and shared path operations without parsing
+rendered help or invoking application input factories and acquisition callbacks
+just to discover command and flag names. This does not select a lifecycle or
+provider API for future dynamic operand or value suggestions.
+
+Completion requests contain partial tokens and cursor context. A future
+completion lookup must accommodate incomplete input without relaxing exact
+matching for execution or requiring partial input to pass execution validation.
+Preserve the distinction between structured paths and supplied argument tokens;
+shell-specific tokenization and quoting belong to that future work.
+
+Shell completion itself is outside this implementation. Do not add completion
+APIs, shell scripts, partial-input lookup machinery, or completion-specific
+tests in this delivery. Internal lookup separation supports the current routing
+and help responsibilities; it does not require a public metadata API or a
+general completion framework. Shell selection, candidate presentation, and
+dynamic value completion remain future design work.
+
 ## Work needed from the baseline
 
 1. Prepare consumer examples for the selected declaration types and shared path handling,
@@ -548,7 +583,9 @@ canonical binding.
    invocation identity. Use canonical flag metadata and the existing parser to
    preserve values and operands, and reuse typed execution machinery. Apply the
    selected short-option grammar and correct explicit empty values for canonical
-   short spellings and aliases together.
+   short spellings and aliases together. Keep metadata lookup separate from
+   execution and help rendering as described under future shell completion,
+   without implementing completion in this delivery.
 6. Add focused behavioral evidence for both example mappings, group aliases,
    longest matches, chains, group composition, cycles and nonterminating prefix
    expansion, collisions, missing targets, same-batch
@@ -569,8 +606,8 @@ canonical binding.
    impact and required consumer action in release notes under the
    [release policy](../policy/release.md#versioning-and-compatibility).
 
-Completion means consumers can declare alternate command paths and flag
+This delivery is complete when consumers can declare alternate command paths
-spellings with minimal wiring and invoke canonical behavior and help through
+and flag spellings with minimal wiring and invoke canonical behavior and help through
 them while canonical ownership and binding semantics stay intact. Installation
 rejects conflicts with canonical commands and applicable flags in either
 registration order.