Merge pull request #125 from eduralph/feat/122-planner-batch-ordering

feat(planner): instruct mindful batch ordering via the brief scheduling fields

Author: eduralph

template/.claude/agents/planner.md.jinja

@@ -48,6 +48,25 @@ directory per chosen issue under it, each with its own `brief.md`. `<id>` is the
 tracker id. The driver then builds and signs off each. Brief only the issues the
 human confirms — quantity is theirs to decide, not yours.
 
+**Order the batch — set the scheduling fields (don't leave the order to chance).** When
+you brief several issues you are also deciding how they interleave: the flow runs the
+batch as a scheduled wave (docs 09). Before writing the briefs, map the batch's real
+shape — which issues build on another's change, and which touch the same files — then
+set, per brief, the three machine-parsed scheduling fields:
+
+- **`Depends on:`** — a genuine build-on dependency; the flow holds this bundle until
+  each prereq is COMPLETE.
+- **`Depends on (merged):`** — the stricter form: hold until the prereq's PR is *merged*;
+  use when this issue edits files a prereq also edits, so Do builds on the merged result
+  instead of colliding at merge time.
+- **`Conflicts with:`** — no dependency, but two issues edit a shared file, so they must
+  never run in the same concurrent wave.
+
+Set these from the batch's *real* dependency/conflict structure — an unordered batch
+either serialises needlessly or lets two bundles collide on a shared file and waste a Do.
+Bare ids only on the value line; put the *why* in `Ordering note:`. Sequencing is the
+human's to confirm (like scope) — **ask when the order isn't clear.**
+
 ## How you work
 
 - **The tracker is the source of truth — go straight to it, don't scan this repo.**

template/templates/brief.md.tpl

@@ -21,6 +21,7 @@
 - **Depends on:** <id>[, <id>…]   (optional — ids only on the value line, any trailing note is ignored; batch/lane scheduling waits until these bundles are COMPLETE before this one runs; docs 09)
 - **Depends on (merged):** <id>[, <id>…]   (optional — ids only on the value line, any trailing note is ignored; stricter than Depends on: hold this bundle until each prereq's PR is MERGED, not merely COMPLETE. Use when this edits files a prereq also edits, so Do builds on the merged result instead of conflicting at merge; docs 09)
 - **Conflicts with:** <id>[, <id>…]   (optional — ids only on the value line, any trailing note is ignored; never co-schedule these in the same concurrent wave, e.g. they edit a shared file; docs 09)
+- **Ordering note:** <optional free text — WHY the scheduling fields above are set as they are (e.g. "depends-on-merged 12 because both edit cache.py"). Not machine-parsed; it documents the human's sequencing decision next to the bare-id fields.>
 - **Surfaces:** <where the change is observable — `gui` (touches the frontend / an E2E
   through the app is needed), `data` (backend/logic only), or `both`. Drives which
   runtime gates apply (e.g. an E2E gate runs only when this is `gui`). Optional.>