Accept ADR 0013 for application alias routing

docs/adr/0013-application-alias-routing.md

@@ -0,0 +1,68 @@
+# ADR 0013: Separate application alias routing from canonical command ownership
+
+## Status
+
+Accepted. Refines [ADR 0011](0011-captured-declarations-and-installation.md)
+by extending its shared installation boundary to application routing rules.
+Its canonical command ownership and declaration principles remain in force.
+
+## Date
+
+2026-10-19
+
+## Context
+
+Applications need alternate command paths and flag spellings that suit their
+operator vocabulary. These conveniences should reuse the behavior supplied by
+application commands and optional integrations. Canonical command families
+already establish ownership of handlers, namespaces, inputs, and invocation
+behavior.
+
+A routing layer allows applications to choose alternate spellings while
+preserving those ownership boundaries. Commands and routing rules have distinct
+roles, and their relationships require validation during application assembly.
+
+## Decision
+
+CommandKit core owns alias declaration, resolution, and coordination with parsing
+and help. Applications choose their alias mappings. Alias infrastructure is
+available independently of optional integrations under the module boundaries
+established by [ADR 0010](0010-optional-integration-modules.md).
+
+Aliases belong to an application routing layer that directs invocations to
+canonical commands and flags. Canonical definitions retain ownership of their
+handlers, inputs, and namespaces. An alternate path within an integration's
+namespace remains an application routing rule; the integration continues to own
+the canonical command family and its operations.
+
+Canonical commands and routing rules are distinct declaration kinds installed
+through a common core assembly boundary. Installation validates their
+relationships together, preserves canonical definitions and namespace ownership,
+and applies the batch-atomicity and retained-error model of ADR 0011 to both
+layers. Declaration capture and reuse follow that existing model.
+
+An invocation through an alias uses the canonical target's parsing, typed
+bindings, validation, and ordinary invocation lifecycle. Execution behavior
+remains with the canonical command and its owning application or integration.
+Core coordinates alternate routing and presentation through the same command
+infrastructure.
+
+## Alternatives considered
+
+| Alternative | Analysis |
+| --- | --- |
+| Install aliases as wrapper commands | Reuses the command tree for discovery, but introduces additional command nodes and handler delegation into namespace ownership and invocation lifetimes. |
+| Have applications rewrite arguments before dispatch | Gives applications direct control over shortcuts, but repeats routing infrastructure and separates alias handling from target validation, parsing, and help. |
+| Register aliases through a separate assembly API | Makes routing declarations explicit, but splits validation of commands and their alternate routes across installation boundaries. Distinct declaration kinds express the separation within one atomic batch. |
+
+## Consequences
+
+Applications can tailor operator vocabulary while reusing canonical behavior.
+Core maintains the relationship between routing rules and canonical definitions
+as declarations are installed. Optional integrations continue to supply their
+command families through the existing ownership model.
+
+Routing, parsing, and help must coordinate across the two layers. Exact API
+shapes, resolution rules, and presentation choices belong in GoDoc and the
+[CLI reference](../cli.md) when implemented. Those details can evolve within
+this architectural separation.

docs/roadmap/aliases.md

@@ -3,6 +3,8 @@
 Status: command- and flag-alias behavior and consumer API direction accepted;
 implementation has not started. OD-1 through OD-6 are resolved. This roadmap
 records the target and work needed before implementation.
+[ADR 0013](../adr/0013-application-alias-routing.md) records the accepted
+architectural ownership and shared installation decisions.
 
 ## Purpose and ownership
 
@@ -565,28 +567,24 @@ dynamic value completion remain future design work.
    covering a command shortcut, a synonym inside an integration namespace, and
    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
-   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. Establish termination-validation behavior with focused evidence for valid
+2. 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
+3. 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.
-5. Integrate command and flag alias resolution with canonical routing, help, and
+4. 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. Keep metadata lookup separate from
    execution and help rendering as described under future shell completion,
    without implementing completion in this delivery.
-6. Add focused behavioral evidence for both example mappings, group aliases,
+5. 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
@@ -598,10 +596,10 @@ dynamic value completion remain future design work.
    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
+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).
-8. Document migration from `...Command` to `...Declaration`, including slice
+7. 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).