From 50c54c229e285c6cf5797e98becee344e50f6693 Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Mon, 19 Oct 2026 00:20:47 +0000
Subject: [PATCH] Record alias chain and group composition decisions

---
 docs/roadmap/aliases.md | 48 ++++++++++++++++++++++++++++-------------
 1 file changed, 33 insertions(+), 15 deletions(-)

diff --git a/docs/roadmap/aliases.md b/docs/roadmap/aliases.md
index 8f6b25b..c58ba60 100644
--- a/docs/roadmap/aliases.md
+++ b/docs/roadmap/aliases.md
@@ -128,14 +128,38 @@ Preserve trailing arguments,
 including flags, operands, explicit empty values, and `--`, for canonical
 parsing. Values and operands are not searched for alias text.
 
-Support alias chains and resolve them to their canonical target. Validate
-targets and reject cycles during installation. Resolution must terminate;
-the treatment of group-prefix composition is part of the remaining detailed
-design.
-
 The initial command-alias feature maps command paths. Preset flags, operand
 transformation, and arbitrary argument rewriting are outside this delivery.
 
+### Chains and group composition
+
+Support alias chains and resolve them to their canonical target. At each lookup,
+select the longest matching command-path prefix, replace it with its target,
+and preserve the remaining tokens. Repeat command-path resolution until the
+canonical route is reached, then parse its inputs normally. Flags, flag values,
+and operands remain outside command-alias matching under the command/operand
+boundary rules below.
+
+A group shortcut provides access to routes beneath its target, including aliases:
+
+```text
+pk                  → promptkit
+promptkit test full → promptkit test all
+```
+
+Here, `pk test full` resolves through `promptkit test full` to
+`promptkit test all`. An explicitly declared `pk test full` alias would take
+precedence over `pk` at the initial lookup. Ordinary chains follow the same
+rules, for example `collections → list collections → promptkit list collections`.
+
+Validate composition during installation and reject cycles and nonterminating
+prefix expansion with diagnostics identifying the participating mappings.
+Checking only for repeated complete paths is insufficient: `a → b extra` and
+`b → a` continually expand the path without repeating it. Analyze prefix
+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.
+
 ### Installation and collisions
 
 Use the shared declaration and installation conventions above for aliases,
@@ -179,8 +203,8 @@ 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.
+conflicting paths and preserve batch atomicity. Apply the chain and group
+composition rules above when validating resolved routes.
 
 ### Execution and help
 
@@ -289,7 +313,8 @@ target validation, and help presentation remain open below.
    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
+   longest matches, chains, group composition, cycles and nonterminating prefix
+   expansion, collisions, missing targets, same-batch
    resolution, later registration, argument preservation, help without
    acquisition, and a single execution lifecycle. Cover application-wide and
    command-scoped flag mappings, attached and separate values, option termination,
@@ -316,13 +341,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-3: Chains and group aliases
-
-How do group aliases compose with more specific aliases and with aliases inside
-their target paths? At what boundaries is resolution repeated? How are cycles
-and nonterminating prefix expansion detected without confusing operands with
-command-path tokens?
-
 ### OD-4: Help and discovery
 
 How are aliases listed, grouped, and described in help? What happens when an