Record canonical collision and deterministic alias rules

docs/roadmap/aliases.md

@@ -69,8 +69,19 @@ Aliases can target individual commands or groups. A group alias preserves
 remaining subcommand tokens. For example, `list collections` can reach
 `promptkit list collections` through the `list` group alias.
 
-Match complete argument tokens at the beginning of the command path. Resolve
-overlapping alias paths using the longest match. Preserve trailing arguments,
+Match exact, complete argument tokens at the beginning of the command path;
+`list` does not match `listing`. Resolve overlapping alias paths using the
+longest matching path, measured by the number of command-path tokens, not
+character count. This rule applies at each command-alias lookup and is
+independent of registration order. Sorting by descending token count and taking
+the first matching prefix is one possible implementation; the algorithm remains
+an implementation choice.
+
+For example, with `list → promptkit list` and
+`list collections → application collections`, the more specific mapping wins
+for `list collections`, while `list prompts` uses the `list` mapping.
+
+Preserve trailing arguments,
 including flags, operands, explicit empty values, and `--`, for canonical
 parsing. Values and operands are not searched for alias text.
 
@@ -94,10 +105,15 @@ targets, collisions, and cycles produce installation errors with useful path
 context. Failed installation preserves the existing application registry and
 alias mappings under the existing batch-atomicity model.
 
-Reject aliases that shadow existing canonical command paths. Preserve that
-protection when later registration adds commands. Detailed prefix interactions
-remain open below. Aliases do not create canonical parent groups, merge
-integration trees, or replace handlers.
+An alias cannot conflict with or overload a canonical command path. Reject such
+a declaration during installation as invalid application configuration. Apply
+the same protection when later registration adds a canonical command conflicting
+with an existing alias. Reject competing mappings from the same source path to
+different targets; registration order must not select a winner. Whether identical
+duplicate declarations are accepted remains open.
+
+Detailed prefix interactions remain open below. Aliases do not create canonical
+parent groups, merge integration trees, or replace handlers.
 
 ### Execution and help
 
@@ -155,6 +171,20 @@ values, explicit empty strings, and operands. The routing layer cooperates with
 the existing parser rather than maintaining a separate interpretation of flag
 arity, boolean syntax, or option termination.
 
+Match the complete flag name. Length precedence does not apply: `--out` and
+`--output` are different names, and only `--out` participates in alias lookup in
+`--out=value`. Scope precedence remains a separate decision. Resolution must
+be deterministic and must not depend on registration order.
+
+### Canonical flag collisions
+
+An alias cannot conflict with or overload an applicable canonical flag spelling.
+Reject conflicts during installation as invalid application configuration.
+Check a command-scoped alias against that command's canonical flags, and an
+application-wide alias across the commands where it applies. Apply the same
+checks when later registration adds canonical declarations. Failed batches
+preserve existing commands and alias mappings.
+
 ### Canonical binding behavior
 
 An alias feeds the same typed binding as its canonical flag. The target retains
@@ -172,8 +202,8 @@ spelling accumulate in order. Alias resolution adds no second conversion or
 input-preparation lifecycle.
 
 Flag aliases do not change canonical flag ownership or add new provider
-capabilities. Short-flag support, chains, collisions, installation validation,
-and help presentation remain open below.
+capabilities. Short-flag support, chains, alias-to-alias scope conflicts,
+target validation, and help presentation remain open below.
 
 ## Work needed from the baseline
 
@@ -203,24 +233,27 @@ and help presentation remain open below.
 
 Completion means consumers can declare alternate command paths and flag
 spellings with minimal wiring and invoke canonical behavior and help through
-them while canonical ownership and binding semantics stay intact. Command alias
-installation provides the selected validation; flag alias installation follows
-the validation rules still to be settled.
+them while canonical ownership and binding semantics stay intact. Installation
+rejects conflicts with canonical commands and applicable flags in either
+registration order. Remaining flag-target and alias-composition validation
+details are still to be settled.
 
 ## Open Decisions
 
 ### OD-1: Public declaration and registration API
 
-What are the exact command- and flag-alias declaration, path representation, and installation
-signatures? How do alias declarations compose with groups, reusable declarations,
-and later `App.Register` calls? What are the duplicate-declaration semantics?
+What are the exact command- and flag-alias declaration, path representation, and
+installation signatures? How do alias declarations compose with groups, reusable
+declarations, and later `App.Register` calls? Are identical duplicate declarations
+accepted?
 
 ### OD-2: Prefix interactions and canonical reachability
 
 How are collisions determined when alias sources or targets overlap canonical
-groups or runnable commands with children? How does longest matching interact
-with operand boundaries? Which later registrations conflict with existing
-aliases? How are ambiguous paths reported?
+groups or runnable commands with children? How does longest-token-path matching
+interact with operand boundaries? How are indirect prefix conflicts detected
+when either aliases or canonical commands are added? How are ambiguous paths
+reported?
 
 ### OD-3: Chains and group aliases
 
@@ -248,5 +281,6 @@ How do application-wide and command-scoped mappings interact when both apply?
 How is an application-wide mapping treated on commands lacking its target flag?
 How are aliases applied to built-in help on groups and at the application root?
 Which short-flag forms are supported? Are flag-alias chains supported, and how
-are collisions, cycles, and missing targets validated at installation and later
-registration? How are flag aliases exposed in help and diagnostic spelling?
+are alias-to-alias conflicts, cycles, and missing targets validated at installation
+and later registration? How are flag aliases exposed in help and diagnostic
+spelling?