ADR 0427: Instruction sources compile in configured order

Status: accepted

[instructions].sources lists the files, or glob patterns, that discern refresh compiles into every agent file after the built-in sections. The resolver collected every match into one set and sorted it by absolute path. The configured list therefore chose which files compiled, never their order.

A project that compiles guidance from more than one source, such as its own rules beside another tool's generated guidance, could not put one ahead of the other. Moving a file or renaming a directory reordered the compiled agent file without any configuration change. The map already described configured order; the code and the config reference described path order.

ADR 0246 settled the same question for scope exports: a list a person writes is a reading order.

resolveInstructionSources in src/lib/paths.ts returns files in the order of the configured entries. The files one glob matches sort by path, which keeps a single pattern's output stable whatever order the filesystem returns. A file that several entries match keeps the position of the first. Agent-file outputs remain excluded, and an entry that matches nothing contributes nothing.

Every consumer of the resolver inherits the order: compilation, the currency check, map integrity, tidy, improvement rules, and doctor.

• Keep path order and document it. Owners would have to rename files to control precedence, and a rename elsewhere in the tree could reorder guidance silently.
• An explicit priority field per source. It adds a second ordering mechanism to a list that already has one.

A project with several sources whose configured order differs from path order sees its agent files reorder once. discern upgrade and the next discern refresh recompile them, and discern done reports the stale copies until then. A project with one source, or with sources already listed in path order, sees no change.

The sources prose in the config schema, template, and reference now states the order rule.