Auto-erase flow-history by default, for trigger.

cylc/flow/commands.py

@@ -457,6 +457,13 @@ async def force_trigger_tasks(
             "at Cylc 8.5."
         )
     yield
+
+    if not flow:
+        # default case: erase flow history before trigger
+        flow_nums = get_flow_nums_set(flow)
+        schd.remove_tasks(tasks, flow_nums)
+        schd.workflow_db_mgr.process_queued_ops()
+
     yield schd.pool.force_trigger_tasks(
         tasks, flow, flow_wait, flow_descr, on_resume
     )

cylc/flow/scheduler.py

@@ -1118,6 +1118,7 @@ def remove_tasks(
 
         if flow_nums is None:
             flow_nums = set()
+
         # Mapping of *relative* task IDs to removed flow numbers:
         removed: Dict[Tokens, FlowNums] = {}
         not_removed: Set[Tokens] = set()

cylc/flow/scripts/trigger.py

@@ -17,18 +17,26 @@
 
 """cylc trigger [OPTIONS] ARGS
 
-Force task(s) to run regardless of prerequisites, even in a paused workflow.
+Force task(s) to run, even in a paused workflow.
 
-Triggering a task that is not yet queued will queue it.
+Triggering a task that is not yet queued will queue it; triggering a queued
+task will run it (so un-queued tasks may need to be triggered twice).
 
-Triggering a queued task runs it immediately.
+Tasks can't be triggered if already active (preparing, submitted, running).
 
-Cylc queues restrict the number of jobs that can be active (submitted or
-running) at once. They release tasks to run when their active task count
-drops below the queue limit.
+Triggering a group of tasks at once:
+  Off-group prerequisites will be force-satisfied; in-group prerequisites
+  will be respected - i.e. left to be satisfied by the triggered flow.
 
-Attempts to trigger active (preparing, submitted, running)
-tasks will be ignored.
+Triggering past tasks:
+  By default the flow-history of target tasks will be erased so that you
+  can re-traverse the past graph without starting a new flow.
+
+Triggering a sub-graph:
+  * Recommended approach: trigger all sub-graph tasks as a group. The forced
+  satisfaction of off-group prerequisites will automatically avoid a stall.
+  * Alternative approach: trigger the initial tasks of the sub-graph to start
+  the flow, and manually set off-flow prerequisites to prevent a stall.
 
 Examples:
   # trigger task foo in cycle 1234 in test
@@ -40,6 +48,11 @@
   # start a new flow by triggering 1234/foo in test
   $ cylc trigger --flow=new test//1234/foo
 
+Cylc queues:
+  Queues limit how many tasks can be active (preparing, submitted, running) at
+  once. Tasks that are ready to run will remained queued until the active task
+  count drops below the queue limit.
+
 Flows:
   Waiting tasks in the active window (n=0) already belong to a flow.
   * by default, if triggered, they run in the same flow

cylc/flow/task_pool.py

@@ -2268,6 +2268,9 @@ def force_trigger_tasks(
             - just spawn (if not already spawned in this flow)
               unless flow-wait is set.
 
+        flow: [] - default
+              ['none'] - no-flow
+
         """
         # Get matching tasks proxies, and matching inactive task IDs.
         existing_tasks, inactive, unmatched = self.filter_task_proxies(