Document workflow trigger semantics

Author: pasunboneleve

CHANGELOG.md

@@ -8,11 +8,20 @@ All notable changes to `devloop` will be recorded in this file.
 - Added a browser reload event server and a `notify_reload` workflow
   action so workflows can explicitly tell downstream browser listeners
   to refresh after successful rebuild/restart steps.
+- Added declarative workflow `triggers` so downstream orchestration can
+  be expressed directly in config instead of being inferred through
+  secondary file watches.
 
 ### Fixed
 - Workflow failures such as process-readiness timeouts now log loudly
   but do not terminate `devloop`, so the watcher stays alive and the
   next successful edit can recover a broken local build.
+- Triggered workflows now run as part of the same execution tree,
+  including when their parent workflow was reached via `run_workflow`.
+- Config validation now rejects ambiguous trigger graphs where a direct
+  trigger target is also reachable through `run_workflow`, and
+  triggered workflows are documented as single-run deduplicated within
+  one execution.
 - Platform-specific release workflows no longer duplicate GitHub release notes when both assets are published to the same tag.
 
 ## [0.6.2] - 2026-03-26

README.md

@@ -223,6 +223,12 @@ endpoint and exposes its URL to child processes as
 `DEVLOOP_BROWSER_EVENTS_URL` so client repositories can attach a tiny
 browser-side `EventSource` listener.
 
+Triggered workflows are deduplicated within one execution. If two
+trigger paths both reach the same workflow, `devloop` runs it once from
+the first path that reaches it. Config validation also rejects graphs
+where a direct trigger target is separately reachable through
+`run_workflow`, because that would make ordering ambiguous.
+
 Hooks can also be observed on the runtime tick when external state
 changes are not represented by file edits. For example:
 

docs/behavior.md

@@ -67,7 +67,13 @@ Workflows run step by step, in order.
 - A step must finish successfully before the next one begins.
 - `run_workflow` executes another named workflow inline.
 - `triggers` run downstream workflows after the workflow succeeds.
+- Triggered workflows are deduplicated across one execution tree. If two
+  trigger paths reach the same workflow, it runs once from the first
+  path that reaches it.
 - Recursive workflow graphs are rejected at config-validation time.
+- Config validation also rejects graphs where a direct trigger target is
+  separately reachable through `run_workflow`, because that would make
+  ordering and duplication ambiguous.
 - `write_state` renders `{{state_key}}` templates against the current
   in-memory session state.
 - `log` also renders templates against the current session state before