#223 - Fix CounterTask outputting its final count several times

[njoubert-cleverage]

Description

Fixes #223.

flush() may be called several times on the same task during a process: once when an upstream iterable task finishes its iterations, then once for each resolved ancestor and for the task itself. The documentation already states that flush() implementations must be idempotent, but CounterTask is not: it outputs its final count on every flush() call.

Other flushable tasks of the bundles (SimpleBatchTask, IterableBatchTask, InputFolderBrowserTask, ProcessLauncherTask, DoctrineBatchWriterTask) empty their buffer on the first flush, so the next calls output nothing.

This PR:

• Make CounterTask::flush() idempotent: a count already outputted by a previous flush is not outputted again (a new count, after new executions, is).
• Document the contract on FlushableTaskInterface (docblock) and in 03-custom_tasks.md: flush() may be called several times and must be idempotent. Update 02-task_types.md and reference/tasks/counter_task.md, which describe the duplicated count.
• Changing the engine so that each task is flushed only once is out of scope (see Rewrite the ProcessManager to simplify each functionnality #88).
• Add tests.

The new regression tests fail on main and pass with this fix. PHPUnit, PHPStan, PHP-CS-Fixer and Rector pass.

Requirements

• Documentation updates
  • Reference
  • Cookbooks
  • Changelog
• Unit tests

Breaking changes

None: the final count is outputted once instead of several times.

🤖 Generated with Claude Code