feat: Orders/formulas structural asymmetry

[donbox]

Problem

Orders and formulas have inconsistent structure in three ways:

1. Orders use subdirectories for single files. Each order requires formulas/orders/<name>/order.toml — a directory containing one file. No order directory in the codebase contains anything besides order.toml. Meanwhile, formulas use flat files: formulas/pancakes.formula.toml. The directory exists solely to provide the order name.

2. Orders are nested under formulas but aren't formulas. Orders reference formulas — they schedule dispatch. They're a peer concept (scheduling vs. workflow definition), not a child. Nesting them under formulas/ misrepresents the relationship.

3. Two locations, different rules. Cities support both formulas/orders/ and top-level orders/. Packs only support formulas/orders/. There's no semantic difference between the two locations — same scanning, same priority, same behavior. The divergence is arbitrary.

4. [formulas].dir is configurable; no other convention-based directory is. scripts/, commands/, doctor/, overlays/ are all discovered by fixed directory name. Only formulas/ has a configurable path via [formulas].dir. This is an odd inconsistency — if someone needs formulas in a non-standard location, that's what packs and imports are for.

Proposed change

• Standardize on top-level orders/ for both cities and packs
• Adopt flat files: orders/<name>.order.toml (matches formula convention — name from filename, no wrapper directory)
• Deprecate formulas/orders/ nesting
• Make formulas/ a fixed convention (remove [formulas].dir), consistent with every other convention-based directory

Alternatives considered

• Keep formulas/orders/ nesting. Preserves current behavior but cements the incorrect parent-child relationship.
• Keep [formulas].dir configurable. Would require making all other convention directories configurable too for consistency — unnecessary complexity.

[donbox]

@csells @julianknutsen

This is the last of the issues that popped out of my scrub.

This one is the most trivial to implement, although it will involve migration of user's definitions (as will the other two).

[donbox]

Adding two related observations from tutorial validation (`docs/tutorials/06-orders.md` and `docs/tutorials/fodder/issues.md` on `tutorials-reviewable`) that fall under the same structural-asymmetry conversation:

1. Orders live in two places

Orders can live in `formulas/orders/` (nested) or top-level `orders/` (peer). There is no semantic difference — same scanning, same priority, same behavior. But the two locations create unnecessary ambiguity, and they aren't even symmetrical: cities support both, packs only support `formulas/orders/`.

Top-level `orders/` is the better choice. Orders aren't formulas — they reference formulas. They're a peer concept (scheduling vs. workflow definition) and belong as a sibling directory alongside `formulas/`, `prompts/`, and `packs/`. Nesting them under `formulas/` misrepresents the relationship and adds a level of indirection for no reason.

Suggestion: Standardize on top-level `orders/` for both cities and packs. Deprecate `formulas/orders/`. This eliminates the arbitrary city-vs-pack divergence and picks the simpler, more conceptually honest location.

2. Each order requires its own subdirectory

Each order currently requires its own subdirectory containing a single `order.toml`. No order directory in the codebase contains anything besides `order.toml` — the directory exists solely to provide the order name. This is unnecessary indirection.

Formulas use a flat file model: `formulas/pancakes.formula.toml`, where the filename provides the name. Orders should follow the same pattern: `orders/health-check.order.toml`. One file per order, filename is the name, no wrapper directories.

This is consistent with the formula convention, eliminates empty directories, and makes order definitions easier to browse (`ls orders/` shows all orders at a glance instead of a list of directories you have to drill into).

Suggestion: Adopt `orders/.order.toml` as the canonical order file format. The `[order]` table wrapper inside the TOML can stay as-is. Deprecate the `orders//order.toml` subdirectory pattern.

Both of these are tutorial-discovery findings, not active blockers, but they're the same conversation as this issue and worth folding into whatever resolution lands here.

[donbox]

cc @julianknutsen — both observations above were found during tutorial validation (06-orders.md and fodder/issues.md on tutorials-reviewable)

[csells]

re: one place for orders -- yes please!

[julianknutsen]

Wasteland sync — tracked as w-fd6e047e39

Field	Value
Wanted ID	w-fd6e047e39
Status	open
Upstream	hop/wl-commons

Last updated by Wendy patrol — 2026-04-09T12:30Z