When regenerating navigation lists in a page source file, support a simple way to override the default discovered navigation list by the presence of a .navigation.lst file. A .navigation.lst file would be discovered up the hierarchy, similar to a .template.* page template file, and the first encountered .navigation.lst would take precedence.
Each line is a reference to an artifact, relative to the directory of the corresponding .navigation.lst file, just like references in a template are relative to the original .template.* file location. These artifacts would simply take the place of any artifacts that might have been discovered. The order of the list is maintained.
Once set, the list will be in effect down the hierarchy until overridden by another .navigation.lst. The .navigation.lst may be empty, indicating no navigation items at all.
If we say that the list doesn't imply order, that could be a problem; the list might contain the parent collection itself (./), in which case the implementation would have to pull it out separately. This is doable, and we might want to do that anyway at some point when ordering (or even assign it some default order). But for now the easier approach might be simply to take the navigation list at face value and use its ordering. Perhaps automatic-ordering is more appropriate in the additive (.navigation+.lst) and subtractive (.navigation-.lst) navigation lists.
An argument for using the list order is that, "if the user didn't want that order, they could have put the order they wanted". But if we allow ordering based on the artifact metadata in e.g. the additive lists, then we have an inconsistency between the two list definitions. And finally if we allow * to be placed between listed elements in a .navigation.lst, how would we allow the actual listings to be interspersed within the * (automatic) list? Perhaps the answer to the last question is that we would allow allow order overrides in parentheses as proposed in GUISE-133; this would allow selectively overriding the order for one item in a .navigation.lst as well, simply by including * and the single listing with its order override.
From the code it appears that it was decided to have the list itself indicate the order of items rather than resorting them based upon their artifact navigation order, if any.
Note that plain navigation lists do not support arbitrary links (e.g. non-relative URL hrefs) because it complicates things to reach out to those links and pull in metadata such as title. In the future we can consider in another ticket if it is practical to support external links somehow.
From the code it appears that the initial implementation of this ticket would not support fragments, e.g. foo.xhtml#bar. That's probably OK at first, as the purpose of this ticket was just to reorder the links. But this is getting refactored as part of GUISE-142, and support for fragments will be added to navigation.lst.