diff --git a/docs/roadmap/aliases.md b/docs/roadmap/aliases.md index cef6c95..dd40ebf 100644 --- a/docs/roadmap/aliases.md +++ b/docs/roadmap/aliases.md @@ -272,9 +272,28 @@ declaring a command alias, using the shared registration conventions above. Support application-wide mappings and mappings scoped to a canonical command. The selected canonical command determines the applicable flag aliases, so a command-scoped mapping works through every command alias that reaches that -target. An application-wide help alias provides the same convenience throughout -the application. Scope precedence and handling of targets unavailable on some -commands remain open. +target. A command-scoped mapping takes precedence over an application-wide +mapping for the same alias spelling. Reject different-target mappings within +the same scope; identical duplicates are harmless. Registration order does not +choose a winner, and neither scope may overload an applicable canonical flag. + +An application-wide mapping is available wherever its target flag exists and +contributes nothing elsewhere. For example, `--colour → --color` need not require +every command to define `--color`. On a command without that target, `--colour` +receives the ordinary unknown-flag error. Reusable application-wide declarations +are valid even when no currently installed command has their target flag. + +A command-scoped mapping requires its named canonical command and target flag +to exist in the complete candidate installation batch. An unavailable explicit +destination is invalid configuration. + +Application-wide mappings also apply to built-in flags at the application root +and on groups. In particular, `--hlep → --help` works wherever canonical +`--help` works, including help for alias-only prefixes. + +Later registration repeats validation against the candidate registry. Newly +installed commands gain applicable application-wide aliases automatically; +canonical spelling collisions reject the batch under the collision rules below. ### Token interpretation @@ -297,7 +316,7 @@ 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 +`--out=value`. Use the scope precedence selected above. Resolution must be deterministic and must not depend on registration order. ### Canonical flag collisions @@ -326,8 +345,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, alias-to-alias scope conflicts, -target validation, and help presentation remain open below. +capabilities. Short-flag support, chains and their validation, and help +presentation remain open below. ## Work needed from the baseline @@ -378,10 +397,8 @@ canonical invocation paths? ### OD-6: Flag alias scope and composition -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 alias-to-alias conflicts, cycles, and missing targets validated at installation -and later registration? How are flag aliases exposed in help and diagnostic -spelling? +Scope precedence, target availability, and application to built-in help are +selected above. Which short-flag forms are supported? Are flag-alias chains +supported, and how do scope precedence and target availability apply through +a chain? How are cycles validated at installation and later registration? +How are flag aliases exposed in help and diagnostic spelling?