From 3e27458f9c64eb839f3e8b4b1e7861fb1932f459 Mon Sep 17 00:00:00 2001
From: finalerock44 <77282157+finalerock44@users.noreply.github.com>
Date: Thu, 13 Aug 2026 10:21:09 +0100
Subject: [PATCH] docs(workspace-config): document executionOrder shape
 validation and fix continueOnFailure default

Two corrections to the executionOrder section, prompted by dcd-cli#110:

- continueOnFailure was documented as defaulting to false. The CLI has always
  defaulted it to true (three read sites agree, and it is now the schema
  default). Corrected, with a note on when to set it to false.
- Added a warning block for the shape mistake the issue reported: a bare list
  of flow names under executionOrder. It is not valid Maestro, older CLI
  versions silently ignored it and ran every flow in parallel while still
  reporting success, and the CLI now rejects it outright. Shows the wrong and
  right forms side by side so it is findable by anyone hitting the error.

Also noted that unrecognised top-level keys are now warned about, which is
what catches flowOrder, a top-level continueOnFailure, and tags: in place of
includeTags/excludeTags.
---
 configuration/workspace-config.md | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/configuration/workspace-config.md b/configuration/workspace-config.md
index 7d67f90..485e158 100644
--- a/configuration/workspace-config.md
+++ b/configuration/workspace-config.md
@@ -59,10 +59,33 @@ executionOrder:
 ```
 
 - `flowsOrder` — list of flow names to run in sequence. A name matches either the `name:` field inside the flow YAML or the filename without extension.
-- `continueOnFailure` — if `true`, subsequent flows in the sequence run even if an earlier one fails. Defaults to `false`.
+- `continueOnFailure` — if `true`, subsequent flows in the sequence run even if an earlier one fails. Defaults to `true`. Set it to `false` when a later flow depends on an earlier one having passed.
+
+{% hint style="warning" %}
+**`executionOrder` must be a map containing `flowsOrder`.** A bare list of flow names is not valid:
+
+```yaml
+# WRONG — rejected by the CLI
+executionOrder:
+  - login
+  - checkout
+```
+
+```yaml
+# RIGHT
+executionOrder:
+  flowsOrder:
+    - login
+    - checkout
+```
+
+The bare-list form is not valid Maestro either. Older CLI versions accepted it and silently ignored it, so the flows ran **in parallel** while the run still reported success — the only symptom was flows executing out of order. The CLI now fails with an error naming the expected shape instead.
+{% endhint %}
 
 {% hint style="info" %}
 If a flow name in `flowsOrder` doesn't match any discovered flow (e.g. after tag filtering), the CLI will emit a warning and lists the available names to help diagnose the mismatch.
+
+Unrecognised top-level keys are also warned about (and ignored), which catches typos like `flowOrder`, a `continueOnFailure` placed at the top level instead of under `executionOrder`, and `tags:` in place of `includeTags`/`excludeTags`.
 {% endhint %}
 
 ### `notifications`