Clarify alias routing interactions and implementation checks

docs/roadmap/aliases.md

@@ -17,10 +17,10 @@ commands:
 ```text
 CLI argument tokens
   → command-path alias resolution
-  → canonical command selection
+  → canonical command or discovery-help context selection
-  → applicable flag-alias resolution using canonical flag metadata
+  → applicable flag-alias resolution using that context's flag metadata
-  → canonical parsing
+  → input parsing
-  → ordinary invocation lifecycle
+  → ordinary invocation lifecycle or discovery help
 ```
 
 Alias declarations do not install new handlers or modify the canonical command
@@ -111,7 +111,7 @@ app, err := commandkit.New(
     ckprompt.Command(suite),
     commandkit.Alias("list collections", "promptkit list collections"),
     commandkit.FlagAlias("--hlep", "--help"),
-    commandkit.FlagAliasFor("promptkit show prompt", "--ver", "--version"),
+    commandkit.FlagAliasFor("promptkit show prompt", "--fmt", "--format"),
 )
 ```
 
@@ -227,6 +227,14 @@ composition so these configuration errors are caught before invocation. An
 arbitrary runtime hop limit is not a substitute for installation validation
 and must not reject an otherwise valid long chain.
 
+A dependency-graph cycle or repeated use of a declaration does not by itself
+establish nontermination. With canonical group `group`, the mappings `a → group`
+and `group again → a` allow `a again again` to terminate: each round consumes
+an `again` token. Validate actual prefix-resolution behavior, including
+terminating repetitions, suffix-dependent cycles, and growing expansions.
+Establish focused evidence for this validation before building the rest of
+routing around the algorithm.
+
 ### Installation and collisions
 
 Use the shared declaration and installation conventions above for aliases,
@@ -238,6 +246,11 @@ 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.
 
+A declared target must resolve entirely to a canonical command or group,
+without leftover operand tokens. For example, reject
+`Alias("fast", "run production")` when canonical `run` takes `production` as
+an operand. Command aliases do not inject fixed operands.
+
 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
@@ -268,6 +281,13 @@ 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.
 
+Explicit longer aliases beneath an alternate spelling still use longest-match
+precedence. With canonical `run TARGET`, `r → run`, and `r full → inspect`,
+`r full` invokes canonical `inspect`; canonical `run full` retains its operand
+meaning. If only `r → run` exists, `r full` reaches `run` with operand `full`,
+which is not searched for aliases after the route resolves. Canonical operand
+protection does not reserve the operand space of every alternate spelling.
+
 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. Apply the chain and group
@@ -324,6 +344,11 @@ and `list --help` display the available routes. This help view is derived from
 alias declarations and creates no canonical group or namespace ownership.
 Bare `list` reports an incomplete command and points to that help.
 
+Routing can select this discovery-help context without selecting a canonical
+command. It uses core's help metadata and applicable application-wide flag
+aliases, so `list --hlep` can request the same help. It neither inherits flags
+from descendant commands nor creates a canonical command node.
+
 Usage errors use the entered path and identify the canonical target when one
 has been resolved, while preserving the canonical command's diagnostic content:
 
@@ -342,6 +367,8 @@ without assigning a canonical identity.
 Applications can declare alternate spellings for canonical flags, including
 `--hlep` mapping to `--help`. Declaring a flag alias should be as simple as
 declaring a command alias, using the shared registration conventions above.
+Validate each source and target as an individual flag spelling; declarations
+do not accept clusters, attached values, or other argument expressions.
 
 Support application-wide mappings and mappings scoped to a canonical command.
 The selected canonical command determines the applicable flag aliases, so a
@@ -371,9 +398,10 @@ canonical spelling collisions reject the batch under the collision rules below.
 
 ### Token interpretation
 
-Resolve command aliases and identify the canonical command before applying its
+Resolve command aliases and select the canonical command or discovery-help
-flag aliases. Use canonical flag metadata to distinguish flag names from values.
+context before applying its flag aliases. Use that context's flag metadata to
-Preserve the existing grammar, including flags interspersed with operands.
+distinguish flag names from values. Preserve the existing grammar, including
+flags interspersed with operands.
 
 | Input | Effect |
 | --- | --- |
@@ -423,10 +451,19 @@ capabilities.
 
 ### Chains and short spellings
 
-Support flag-alias chains, such as `--colour → --hue → --color`. At each step,
+Support flag-alias chains, such as `--colour → --hue → --color`. When resolving
-use the selected command's effective mappings, with command-scoped mappings
+a target, an existing canonical flag spelling terminates the chain. Otherwise,
-taking precedence over application-wide mappings. Resolve to the final
+look up the next alias using the selected context's effective mappings, with
-canonical flag and use its binding.
+command-scoped mappings taking precedence over application-wide mappings.
+Resolve to the final canonical flag and use its binding. Validate applicable
+alias-source collisions separately; a canonical endpoint does not excuse a
+conflicting source declaration.
+
+For example, given canonical `--color` and global mappings
+`--color → --missing` and `--colour → --color`, the first mapping contributes
+nothing while `--missing` is unavailable. The second still reaches canonical
+`--color`. If later registration makes `--missing` available in that context,
+the first mapping becomes a canonical spelling collision and the batch fails.
 
 Apply target-availability rules to the final destination. An application-wide
 chain contributes nothing where its final canonical flag is unavailable. A
@@ -497,16 +534,22 @@ canonical binding.
    command and flag ownership in an ADR. Keep exact API, matching, and presentation
    details in their appropriate contracts. No relaxation of canonical namespace
    ownership is selected.
-3. Implement the selected declaration types and shared path primitives. Extend
+3. Establish termination-validation behavior with focused evidence for valid
+   repetitions, suffix-dependent cycles, and growing prefix expansions before
+   building the rest of routing around the algorithm.
+4. Implement the selected declaration types and shared path primitives. Define
+   and verify installation handling for nil declarations and zero `RoutingRule`
+   values alongside the existing invalid-zero and explicit-absence command
+   contracts. Validate flag declarations as individual spellings. Extend
    installation to validate aliases and commands against the complete candidate
    batch, preserving retained errors and atomicity. Keep aliases
    independent of optional-library dependencies and backend-specific exports.
-4. Integrate command and flag alias resolution with canonical routing, help, and
+5. Integrate command and flag alias resolution with canonical routing, help, and
    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.
-5. Add focused behavioral evidence for both example mappings, group aliases,
+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
    resolution, later registration, argument preservation, help without
@@ -515,9 +558,16 @@ canonical binding.
    mixed canonical/alias repetitions, flag chains and scope overrides, short
    aliases, mixed clusters, attached values, explicit empty-value correction,
    flag help and diagnostics, and unchanged typed binding semantics.
-6. Add maintained consumer examples and update GoDoc, the CLI reference, consumer
+   Include discovery-help contexts without canonical commands, longer aliases
+   beneath operand-taking command shortcuts, rejection of operand-bearing
+   targets, and canonical flag endpoints alongside inactive global mappings.
+7. Add maintained consumer examples and update GoDoc, the CLI reference, consumer
    guidance, and internal documentation when implementation lands. Validate the
    affected modules under the [developer guide](../development.md).
+8. Document migration from `...Command` to `...Declaration`, including slice
+   conversion, and the explicit empty-value correction. Include the compatibility
+   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
 spellings with minimal wiring and invoke canonical behavior and help through