diff --git a/docs/roadmap/aliases.md b/docs/roadmap/aliases.md index a55148e..8f6b25b 100644 --- a/docs/roadmap/aliases.md +++ b/docs/roadmap/aliases.md @@ -120,6 +120,10 @@ 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. +Once a matching alias is selected, resolve that route and apply canonical +validation. A validation failure reports an error; it does not retry a shorter +alias that could invoke a different command. + Preserve trailing arguments, including flags, operands, explicit empty values, and `--`, for canonical parsing. Values and operands are not searched for alias text. @@ -150,8 +154,33 @@ with an existing alias. Reject competing mappings from the same source path to different targets; registration order must not select a winner. Identical duplicate mappings are accepted under the shared registration conventions. -Detailed prefix interactions remain open below. Aliases do not create canonical -parent groups, merge integration trees, or replace handlers. +Aliases do not create canonical parent groups, merge integration trees, or +replace handlers. + +### Prefix interactions and canonical reachability + +Alias paths may share prefixes with canonical paths when they introduce a +distinct route. Preserve existing canonical invocations, including the declared +operand space of runnable commands. + +| Canonical declaration | Proposed alias | Result | +| --- | --- | --- | +| `promptkit test all` | `promptkit test full` → `promptkit test all` | Allow the distinct route beneath the shared prefix. | +| `list projects` | `list collections` → `promptkit list collections` | Allow the distinct route beneath the shared prefix. | +| `list` group | `list` → `promptkit list` | Reject replacement of the canonical group path. | +| `run` accepts an operand | `run full` → another command | Reject interception of `full` in the canonical command's operand space. | + +Determine command and operand boundaries from declared command structure and +argument metadata, without executing handlers or application validation. +Longest-path matching chooses among valid aliases; it does not authorize +consumption of canonical operands. Sharing a runnable ancestor alone does not +establish a conflict: check whether the proposed route intercepts that +ancestor's operands or an existing canonical child route. + +Check these conflicts against the complete candidate registry when adding +either aliases or canonical commands, including later registration. Report the +conflicting paths and preserve batch atomicity. Chain and group-prefix +composition are addressed under OD-3. ### Execution and help @@ -287,14 +316,6 @@ together? How do collections of reusable declarations and group composition interact with application-root alias paths? What exact whitespace parsing and path validation rules accompany the selected string representation? -### 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-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 How do group aliases compose with more specific aliases and with aliases inside