feat(flow): cadence-gate the auto-Act after a flow (#109)

`pdca flow` auto-ran the Act leaf after every COMPLETE — including single- and
few-item flows. But Act is a cross-cycle cadence beat: it reviews FROZEN cycles across
the index for recurring signals and only yields a real delta once enough cycles have
accumulated. Auto-running it after one slice spends an interactive leaf on insufficient
signal and conflates the per-contribution loop with the cross-cycle cadence.

Gate the auto-run on a configurable cadence that PERSISTS across flow invocations: run
Act only when `[driver].act_cadence` (default 5) cycles have frozen SINCE the last Act.
The "since last Act" count is derived from a durable marker (the frozen-bundle count at
the last review, in process/.act-reviewed) — so five separate one-bundle flows trip it
on the fifth, and it works even when a command-mode Act writes no act-log entry (the
review still happened). Below the threshold the flow skips with a hint; `pdca act log`
runs Act on demand (and resets the cadence); `--no-act` still forces skip; cadence 1
restores run-after-every-flow.

- config: [driver].act_cadence (floor 1).
- act: mark_reviewed / cycles_since_review / act_due (frozen is monotonic, so
  current-minus-marker is the unreviewed count).
- leaves.run_act resets the marker whenever Act runs (both modes); cli `act log
  --append` resets it too.
- flow: _maybe_run_act gates both the single and batch auto-run.

Tests: ActCadence — Act held below cadence then fires on the 3rd flow (persistence
across invocations), and the marker resets after a run. Existing flow tests set
act_cadence=1 to keep asserting Act-after-flow. Full suite: 171 OK.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Eduard Ralph <15236434+eduralph@users.noreply.github.com>

Author: eduralph

template/pdca.toml.jinja

@@ -35,6 +35,13 @@ lanes = 1
 # `$PDCA_WORKTREE` too (see the gate examples below). On by default; best-effort (a target
 # that isn't a worktree-capable git checkout falls back to in-place). Set false to disable.
 worktree = true
+# Act cadence (issue #109). Act is a cross-cycle beat that yields a real delta only once
+# enough cycles have frozen to show a pattern, so `pdca flow` auto-runs it only when this
+# many cycles have frozen SINCE the last Act review — counted across flow invocations
+# (five one-bundle flows trip it on the fifth), not per-run. Below the threshold the flow
+# skips Act with a hint; `pdca act log` runs it on demand and `--no-act` always skips.
+# Set to 1 to run Act after every completed flow (the prior behaviour).
+act_cadence = 5
 # Close-disposition fast path (issue #60). A bundle whose brief's `Disposition hint`
 # matches one of these close / no-fix classes skips the builder + reviewer model leaves
 # (the engine's only token spend) and routes straight to sign-off, where the human

template/src/pdca_harness/act.py

@@ -48,6 +48,45 @@ def frozen_bundles(cfg: Config) -> list[Path]:
     )
 
 
+# ----------------------------------------------------------------------------
+# Cadence (issue #109): Act yields a real delta only once enough cycles have frozen to
+# show a pattern. The flow auto-runs it only when this many cycles have frozen SINCE the
+# last Act — counted from a durable marker (the frozen count at the last review) so it
+# holds across flow invocations, and works even when a command-mode Act writes no
+# act-log entry (the model judged "no delta"). Frozen bundles are monotonic (COMPLETE is
+# terminal), so current-minus-marker is the count of unreviewed cycles.
+# ----------------------------------------------------------------------------
+_CADENCE_MARKER = ".act-reviewed"  # holds the frozen-bundle count at the last Act
+
+
+def mark_reviewed(cfg: Config) -> None:
+    """Record that Act just ran: stamp the current frozen-bundle count (issue #109)."""
+    cfg.process_dir.mkdir(parents=True, exist_ok=True)
+    (cfg.process_dir / _CADENCE_MARKER).write_text(
+        f"{len(frozen_bundles(cfg))}\n", encoding="utf-8")
+
+
+def cycles_since_review(cfg: Config) -> int:
+    """How many cycles have frozen since the last Act (issue #109).
+
+    ``current frozen count − marker`` (no marker ⇒ all frozen cycles count). Never
+    negative, so a deleted bundle can't wedge the cadence.
+    """
+    marker = cfg.process_dir / _CADENCE_MARKER
+    last = 0
+    if marker.exists():
+        try:
+            last = int(marker.read_text(encoding="utf-8").strip() or 0)
+        except ValueError:
+            last = 0
+    return max(0, len(frozen_bundles(cfg)) - last)
+
+
+def act_due(cfg: Config) -> bool:
+    """True iff enough cycles have frozen since the last Act to warrant a review (#109)."""
+    return cycles_since_review(cfg) >= cfg.act_cadence
+
+
 def index(cfg: Config, since: str | None = None) -> list[ActEntry]:
     """Extract §6/§7/§9/§10 from each frozen bundle, newest filtering via §9 date."""
     entries = [_extract(d / "SUMMARY.md", d) for d in frozen_bundles(cfg)]

template/src/pdca_harness/cli.py

@@ -424,6 +424,7 @@ def _act_log(cfg: Config, args: argparse.Namespace) -> int:
     text = act.scaffold_entry(entries, act.patterns(entries), date=args.date)
     if args.append:
         log = act.append_entry(cfg, text)
+        act.mark_reviewed(cfg)  # a manual Act review resets the flow cadence too (#109)
         print(f"appended entry to {log}")
     else:
         print(text)

template/src/pdca_harness/config.py

@@ -122,6 +122,12 @@ class Config:
     # checkout directly, as before). Best-effort: a target that isn't a worktree-capable
     # git checkout silently falls back to in-place.
     worktree: bool = True
+    # Act cadence (issue #109): Act is a cross-cycle beat that only yields a real delta
+    # once enough cycles have frozen to show a pattern, so ``flow`` auto-runs it only when
+    # this many cycles have frozen SINCE the last Act review (counted across flow
+    # invocations, not per-run). Below it, the flow skips Act with a hint. ``1`` restores
+    # run-after-every-flow; ``--no-act`` always forces skip. ``[driver].act_cadence``.
+    act_cadence: int = 5
     # Close-disposition fast path (issue #60): the disposition-hint classes that mark a
     # bundle as close / no-fix, so the driver skips the builder + reviewer leaves and
     # routes it straight to sign-off. ``[driver].close_dispositions`` in pdca.toml; the
@@ -207,6 +213,7 @@ def leaf(name: str) -> LeafConfig:
             lanes = int(os.environ["PDCA_LANES"])
         lanes = max(1, lanes)
         worktree = bool(driver_cfg.get("worktree", True))  # issue #94; on by default
+        act_cadence = max(1, int(driver_cfg.get("act_cadence", 5)))  # issue #109
 
         # Close-disposition classes (issue #60): a configured list retunes the default
         # for an instance's tracker vocabulary; absent ⇒ the built-in default.
@@ -244,6 +251,7 @@ def leaf(name: str) -> LeafConfig:
             gates_runner=gates_runner,
             lanes=lanes,
             worktree=worktree,
+            act_cadence=act_cadence,
             close_dispositions=close_dispositions,
         )
 

template/src/pdca_harness/flow.py

@@ -24,7 +24,7 @@
 import threading
 from pathlib import Path
 
-from . import brief, driver, lane, leaves, merged, publish, queue, signoff, state
+from . import act, brief, driver, lane, leaves, merged, publish, queue, signoff, state
 from .config import Config
 
 
@@ -117,6 +117,27 @@ def _signoff_and_apply(
     return _apply_decision(cfg, d, by=by, today=today, apply_now=apply_now)
 
 
+def _maybe_run_act(cfg: Config, today: str, *, any_complete: bool) -> None:
+    """Run the Act beat after a flow only when it's *due* by cadence (issue #109).
+
+    Act is a cross-cycle beat that yields a real delta only once enough cycles have
+    frozen to show a pattern, so auto-running it after every small flow spends an
+    interactive leaf on insufficient signal. Run it only when ``act_cadence`` cycles have
+    frozen SINCE the last Act (counted from a durable marker, so it holds across separate
+    flow invocations — five one-bundle flows trip it on the fifth). Below the threshold,
+    skip with a hint; ``--no-act`` (``do_act=False``) still forces skip upstream.
+    """
+    if not any_complete:
+        return
+    if act.act_due(cfg):
+        leaves.run_act(cfg, today)
+    else:
+        n = act.cycles_since_review(cfg)
+        print(f"flow: Act skipped — {n} cycle(s) frozen since the last Act "
+              f"(cadence {cfg.act_cadence}); run `pdca act log` when the backlog is "
+              f"worth a review.", file=sys.stderr)
+
+
 def _plan_if_unplanned(cfg: Config, d: Path, csv: str | None) -> bool:
     """If the bundle has no brief, run the (single) Plan leaf. Return True if planned."""
     if state.state(d) != state.UNPLANNED:
@@ -166,8 +187,8 @@ def flow(
         if rc:
             print(f"flow: issue_{issue_id} is COMPLETE but publish did not complete "
                   f"(rc {rc}) — NOT published; run `pdca publish {issue_id}`.", file=sys.stderr)
-    if do_act and final == state.COMPLETE:
-        leaves.run_act(cfg, today)
+    if do_act:
+        _maybe_run_act(cfg, today, any_complete=(final == state.COMPLETE))
     return final
 
 
@@ -431,8 +452,9 @@ def _drive_and_act(
                     print(f"flow: {d.name} is COMPLETE but publish did not complete "
                           f"(rc {rc}) — NOT published; run `pdca publish "
                           f"{d.name.removeprefix('issue_')}`.", file=sys.stderr)
-    if do_act and any(s == state.COMPLETE for s in results.values()):
-        leaves.run_act(cfg, today)
+    if do_act:
+        _maybe_run_act(cfg, today,
+                       any_complete=any(s == state.COMPLETE for s in results.values()))
     return results
 
 

template/src/pdca_harness/leaves.py

@@ -697,8 +697,11 @@ def signoff_rationale(d: Path) -> str:
 def run_act(cfg: Config, date: str) -> None:
     if cfg.act.mode == "command":
         _invoke(cfg.act, cfg.root, _act_prompt(cfg, date))
-        return
-    _stub_act(cfg, date)
+    else:
+        _stub_act(cfg, date)
+    # Reset the cadence marker (issue #109) whenever the Act beat runs — even if a
+    # command-mode Act judged "no delta" and wrote no act-log entry, the review happened.
+    act_mod.mark_reviewed(cfg)
 
 
 def _act_prompt(cfg: Config, date: str) -> str:

template/tests/test_flow_slice.py

@@ -19,7 +19,7 @@
 from types import SimpleNamespace
 from unittest import mock
 
-from pdca_harness import brief, cli, driver, flow, leaves, queue, signoff, state
+from pdca_harness import act, brief, cli, driver, flow, leaves, queue, signoff, state
 from pdca_harness.config import Config, LeafConfig
 
 TEMPLATES = Path(__file__).resolve().parents[1] / "templates"
@@ -45,6 +45,7 @@ def _stub_config(root: Path) -> Config:
         signoff=LeafConfig(mode="stub", family="claude", interactive=True),
         publisher=LeafConfig(mode="stub", family="claude", interactive=True),
         act=LeafConfig(mode="stub", family="claude", interactive=True),
+        act_cadence=1,  # most flow tests assert Act runs after a flow; cadence #109 tested separately
     )
 
 
@@ -1017,5 +1018,39 @@ def test_authored_brief_reads_planned(self) -> None:
         self.assertEqual(state.state(d), state.PLANNED)
 
 
+class ActCadence(unittest.TestCase):
+    """flow auto-runs Act only when act_cadence cycles have frozen since the last Act —
+    counted across flow invocations, not per-run (issue #109)."""
+
+    def setUp(self) -> None:
+        self.tmp = Path(tempfile.mkdtemp())
+        self.cfg = _stub_config(self.tmp)
+        self.cfg.act_cadence = 3
+
+    def tearDown(self) -> None:
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def _log(self) -> Path:
+        return self.cfg.process_dir / "act-log.md"
+
+    def test_act_held_below_cadence_then_fires_across_flows(self) -> None:
+        # Three separate single-bundle flows: Act must NOT run until the 3rd freezes the
+        # third cycle (cadence 3), proving the gate persists across invocations.
+        for i in (1, 2):
+            flow.flow(self.cfg, f"AC{i}", do_act=True, today="2026-06-04")
+            self.assertFalse(self._log().exists(), f"Act ran too early (after flow {i})")
+        flow.flow(self.cfg, "AC3", do_act=True, today="2026-06-04")
+        self.assertTrue(self._log().exists())          # the 3rd frozen cycle trips cadence
+
+    def test_act_resets_after_running(self) -> None:
+        for i in (1, 2, 3):
+            flow.flow(self.cfg, f"R{i}", do_act=True, today="2026-06-04")
+        self.assertTrue(self._log().exists())
+        self.assertEqual(act.cycles_since_review(self.cfg), 0)   # marker reset to frozen count
+        before = self._log().read_text(encoding="utf-8")
+        flow.flow(self.cfg, "R4", do_act=True, today="2026-06-04")   # only 1 since → below cadence
+        self.assertEqual(self._log().read_text(encoding="utf-8"), before)  # no new Act entry
+
+
 if __name__ == "__main__":
     unittest.main()