Add flag alias direction to alias roadmap

docs/roadmap/aliases.md

@@ -1,12 +1,12 @@
 # Application-owned aliases
 
-Status: command-alias direction accepted; implementation has not started.
+Status: command- and flag-alias directions accepted; implementation has not
-Public API and remaining routing details are open. Flag aliasing is under
+started. Public API and remaining routing details are open. This roadmap records
-discussion. This roadmap records the target and work needed before implementation.
+the target and work needed before implementation.
 
 ## Purpose and ownership
 
-Make alternate command spellings and shorter paths simple for consuming
+Make alternate command paths and flag spellings simple for consuming
 applications to declare. CommandKit core owns alias registration, resolution,
 and integration with routing and help. Applications choose their aliases.
 Integrated libraries continue to own their canonical command behavior.
@@ -17,7 +17,9 @@ commands:
 ```text
 CLI argument tokens
   → command-path alias resolution
-  → canonical command routing and parsing
+  → canonical command selection
+  → applicable flag-alias resolution using canonical flag metadata
+  → canonical parsing
   → ordinary invocation lifecycle
 ```
 
@@ -28,6 +30,10 @@ placement rules in [ADR 0011](../adr/0011-captured-declarations-and-installation
 and the [architecture policy](../policy/architecture.md) continue to govern
 canonical command installation.
 
+Flag aliases likewise leave canonical flag definitions and typed bindings
+unchanged. This is one conceptual routing layer; its internal implementation
+cooperates with the existing parser to preserve token interpretation.
+
 ## Current baseline
 
 Core captures reusable `Command` declarations and installs them through `New`
@@ -115,45 +121,97 @@ Alias help describes the canonical target's inputs using the alias invocation
 path and identifies the canonical command. Root help presents aliases separately
 from canonical commands. Group help and discovery details remain to be specified.
 
+## Selected flag-alias behavior
+
+### Spellings and scopes
+
+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; the exact Go API remains open.
+
+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.
+
+### Token interpretation
+
+Resolve command aliases and identify the canonical command before applying its
+flag aliases. Use canonical flag metadata to distinguish flag names from values.
+Preserve the existing grammar, including flags interspersed with operands.
+
+| Input | Effect |
+| --- | --- |
+| `list collections --hlep` | Resolve the command path and route `--hlep` to canonical help. |
+| `foo --colour=blue` | With `--colour` mapped to `--color`, preserve `blue` as the value. |
+| `foo --message=--hlep` | Preserve the value `--hlep`. |
+| `foo --message --hlep` | When `--message` consumes a value, preserve `--hlep` as that value. |
+| `foo -- --hlep` | Preserve the operand `--hlep` after the option terminator. |
+
+Only tokens interpreted as flag names participate in flag aliasing. Preserve
+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.
+
+### Canonical binding behavior
+
+An alias feeds the same typed binding as its canonical flag. The target retains
+its value conversion, defaults, required-value checks, presence tracking,
+repetition rules, and behavior. Mixed spellings retain invocation order:
+
+```text
+foo --color red --colour blue
+```
+
+With `--colour` mapped to singleton `--color`, the normal last-occurrence rule
+selects `blue`. Earlier invalid occurrences remain errors under the existing
+conversion contract. For a repeatable target, occurrences through either
+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.
+
 ## Work needed from the baseline
 
 1. Settle the public alias API and the open routing details with consumer examples
    covering a command shortcut, a synonym inside an integration namespace, and
-   a group shortcut.
+   a group shortcut, an application-wide help flag alias, and a command-scoped
+   flag alias reached through a command shortcut.
 2. Capture the durable separation between application alias routing and canonical
-   namespace ownership in an ADR. Keep exact API, matching, and presentation
+   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. 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 alias resolution with canonical routing, help, and invocation
+4. Integrate command and flag alias resolution with canonical routing, help, and
-   identity. Reuse the existing parser and typed execution machinery.
+   invocation identity. Use canonical flag metadata and the existing parser to
+   preserve values and operands, and reuse typed execution machinery.
 5. Add focused behavioral evidence for both example mappings, group aliases,
    longest matches, chains and cycles, collisions, missing targets, same-batch
    resolution, later registration, argument preservation, help without
-   acquisition, and a single execution lifecycle.
+   acquisition, and a single execution lifecycle. Cover application-wide and
+   command-scoped flag mappings, attached and separate values, option termination,
+   mixed canonical/alias repetitions, and unchanged typed binding semantics.
 6. 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).
 
-Completion means consumers can declare alternate paths with minimal wiring,
+Completion means consumers can declare alternate command paths and flag
-receive installation-time feedback, and invoke canonical behavior and help
+spellings with minimal wiring and invoke canonical behavior and help through
-through those paths while canonical namespace ownership stays intact.
+them while canonical ownership and binding semantics stay intact. Command alias
-
+installation provides the selected validation; flag alias installation follows
-## Flag aliasing under discussion
+the validation rules still to be settled.
-
-The same application routing concept may support alternate flag spellings,
-such as `--hlep` mapping to `--help`, while leaving canonical flags and bindings
-unchanged. The user-facing API should be comparably simple to command aliases.
-Scope, token handling, registration, and help behavior need further discussion;
-no specific flag-alias API or resolution policy is selected here.
 
 ## Open Decisions
 
 ### OD-1: Public declaration and registration API
 
-What are the exact alias declaration, path representation, and installation
+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?
 
@@ -186,7 +244,9 @@ and diagnostic presentation?
 
 ### OD-6: Flag alias scope and composition
 
-What is the flag-alias API and its installation scope? How does it compose with
+How do application-wide and command-scoped mappings interact when both apply?
-command aliases, canonical local flags, and built-in help? Which long and short
+How is an application-wide mapping treated on commands lacking its target flag?
-flag forms are supported? How are values, `--`, chains, collisions, missing
+How are aliases applied to built-in help on groups and at the application root?
-targets, help, and diagnostic spelling handled?
+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?