@deftai/directive-content 0.59.0 → 0.61.0

package/scripts/resume_conditions.py

@@ -1,706 +0,0 @@
-"""resume_conditions.py -- defer ``--resume-on`` grammar + evaluator (#1123 / D3 of #1119).
-
-Public surface
---------------
-
-* :func:`parse` -- structurally validate a resume-condition expression and
-  return an :class:`Expression` AST. Raises :class:`ResumeGrammarError`
-  with a human-readable message on the first malformed atom / composition.
-* :func:`evaluate` -- evaluate a parsed AST against a :class:`ResumeContext`
-  snapshot and return a bool.
-* :func:`build_context` -- derive a :class:`ResumeContext` from the
-  framework's on-disk state (unified ``.deft-cache/github-issue/`` cache
-  for closed/merged refs, ``vbrief/pending/`` for the count, ``today`` for
-  the date comparison). Pure-stdlib; no live ``gh`` calls.
-* :func:`evaluate_resume_eligibility` -- the orchestration entry point
-  consumed by ``task triage:audit --evaluate-resume`` and
-  ``task triage:refresh-active``. Walks the audit log, identifies open
-  ``defer`` entries with a non-null ``resume_on``, evaluates each against
-  the provided context, and APPENDS a new ``resume-eligible`` audit entry
-  (with ``prior_decision_id`` pointing at the original ``defer``) for
-  each condition that fires. Idempotent: re-running the evaluation does
-  NOT duplicate ``resume-eligible`` entries.
-
-Grammar (minimal viable v1, per issue #1123)
--------------------------------------------
-
-Atomic conditions::
-
-    ref:closed:#N                  -- fires when issue/PR N is closed in the cache
-    ref:merged:#N                  -- fires when PR N is merged in the cache
-    date:>=YYYY-MM-DD              -- fires when current date is at or past target
-    pending-count:>=N              -- fires when len(vbrief/pending/) >= N
-    pending-count:<=N              -- fires when len(vbrief/pending/) <= N
-    slice-wave-ready:<slice_id>:<wave>
-                                   -- fires when every child of <slice_id>
-                                      in an earlier wave is closed (#1132 /
-                                      D13). ``<slice_id>`` is a UUID; ``<wave>``
-                                      is a positive int. Sourced from
-                                      vbrief/.eval/slices.jsonl.
-
-Top-level composition (no nested parens / NOT in v1)::
-
-    <atomic> AND <atomic>   -- fires when both atomics fire
-    <atomic> OR  <atomic>   -- fires when either atomic fires
-
-Anything else is a grammar error and rejected at write time by
-:func:`scripts.triage_actions.defer` and at evaluation time by
-:func:`parse`. Whitespace around ``AND`` / ``OR`` is required; the
-parser does not collapse arbitrary spacing into the operator token.
-
-Design notes
-------------
-
-* The framework MUST NOT auto-un-defer. ``resume-eligible`` is a marker
-  that surfaces the item at the top of D11's ``[RESUME]`` group; the
-  operator still decides whether to re-triage with current data.
-* Closed / merged signals come from the existing unified-cache
-  ``state`` field (``"open" | "closed"``). The cache writer is owned
-  by ``scripts/cache.py`` (#883 Story 2); this module is read-only.
-* ``ref:closed:#N`` fires for BOTH issues and PRs that have transitioned
-  to ``closed``; ``ref:merged:#N`` is stricter and requires the cached
-  payload to carry ``"merged": true`` (PRs only). A PR that is closed
-  without merging fires ``ref:closed`` but NOT ``ref:merged``.
-* Re-evaluation idempotency is enforced by scanning prior audit entries:
-  if a ``resume-eligible`` row already exists for the defer's
-  ``decision_id``, no new row is appended. A subsequent ``reset`` /
-  re-defer wipes the marker and allows the next evaluation pass to
-  surface the item again.
-"""
-
-from __future__ import annotations
-
-import contextlib
-import json
-import logging
-import re
-import sys
-from collections.abc import Iterable
-from dataclasses import dataclass, field
-from datetime import UTC, date, datetime
-from pathlib import Path
-from typing import Any, cast
-
-# Make sibling scripts importable when invoked as ``python scripts/resume_conditions.py``.
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-
-# Optional dependency: ``candidates_log`` is the canonical append-only
-# audit-log writer (#845 Story 2). Guarded so this module imports cleanly
-# on a checkout that has not yet rebased onto Story 2 (tests substitute a
-# fake via ``monkeypatch.setattr``).
-try:  # pragma: no cover -- exercised once #845 Story 2 lands.
-    import candidates_log  # type: ignore[import-not-found]
-except ImportError:  # pragma: no cover
-    candidates_log = None  # type: ignore[assignment]
-
-# Optional dependency: ``slice_record`` is the slicing-cohort writer
-# introduced alongside this grammar extension (#1132 / D13). The
-# ``slice-wave-ready:<slice_id>:<wave>`` atomic reads slices.jsonl via
-# this module. Guarded so the grammar still loads on pre-D13 checkouts.
-try:  # pragma: no cover -- exercised once #1132 lands.
-    import slice_record  # type: ignore[import-not-found]
-except ImportError:  # pragma: no cover
-    slice_record = None  # type: ignore[assignment]
-
-LOG = logging.getLogger(__name__)
-
-# ---------------------------------------------------------------------------
-# Public constants
-# ---------------------------------------------------------------------------
-
-#: Audit-log decision tag emitted when a resume condition fires. Mirrors
-#: the addition to ``vbrief/schemas/candidates.schema.json``'s ``decision``
-#: enum (the schema and this constant MUST stay in lockstep).
-RESUME_ELIGIBLE_DECISION: str = "resume-eligible"
-
-#: Audit-log actor tag for evaluator-driven appends.
-EVALUATOR_ACTOR: str = "agent:resume-evaluator"
-
-#: Filesystem-relative location of the unified content cache root.
-CACHE_DIR_NAME: str = ".deft-cache"
-
-#: Cache source layer the resume evaluator reads.
-CACHE_SOURCE_GITHUB_ISSUE: str = "github-issue"
-
-#: vBRIEF lifecycle folder counted by ``pending-count:`` atoms. Mirrors
-#: the D4 (#1124) cap target; D3 uses ``pending/`` ONLY (NOT ``active/``)
-#: because the issue body's example
-#: ``ref:closed:#1121 AND pending-count:>=18`` describes the operator's
-#: "should I revisit this defer now that pending has accumulated?" intent,
-#: which is about the proposed-but-not-yet-active backlog.
-PENDING_LIFECYCLE_DIR: str = "pending"
-
-
-class ResumeGrammarError(ValueError):
-    """Raised when a resume-condition expression fails to parse."""
-
-
-# ---------------------------------------------------------------------------
-# AST
-# ---------------------------------------------------------------------------
-
-
-@dataclass(frozen=True)
-class Atomic:
-    """One atomic resume condition.
-
-    ``kind`` is one of:
-
-    * ``"ref-closed"`` -- ``value`` is the int issue / PR number.
-    * ``"ref-merged"`` -- ``value`` is the int PR number.
-    * ``"date-ge"``    -- ``value`` is a :class:`datetime.date`.
-    * ``"pending-count-ge"`` -- ``value`` is the int threshold.
-    * ``"pending-count-le"`` -- ``value`` is the int threshold.
-    * ``"slice-wave-ready"`` -- ``value`` is the int wave threshold;
-      :attr:`slice_id` carries the cohort identifier (#1132 / D13).
-
-    The dataclass is intentionally simple -- the renderer round-trips
-    via :attr:`raw` so the original operator-supplied text is preserved
-    in error messages and audit-log debugging.
-    """
-
-    kind: str
-    value: int | date
-    raw: str
-    #: Slice identifier carried by ``slice-wave-ready`` atoms (#1132). UUID
-    #: string; empty for every other atomic kind.
-    slice_id: str = ""
-
-
-@dataclass(frozen=True)
-class Expression:
-    """Top-level resume-condition expression.
-
-    ``op`` is one of ``"ATOM" | "AND" | "OR"``. For ``"ATOM"``, ``left``
-    holds the only atomic and ``right`` is ``None``. For ``"AND"`` /
-    ``"OR"``, both ``left`` and ``right`` are :class:`Atomic` instances
-    (nesting is intentionally not supported in v1 per the issue body).
-    """
-
-    op: str
-    left: Atomic
-    right: Atomic | None = None
-    raw: str = ""
-
-
-@dataclass(frozen=True)
-class ResumeContext:
-    """Snapshot of on-disk state the evaluator compares atomic conditions against.
-
-    Attributes:
-        today: Current calendar date in UTC. Compared against
-            ``date:>=YYYY-MM-DD`` atoms.
-        closed_refs: Set of issue / PR numbers whose cached ``state``
-            is ``"closed"``.
-        merged_refs: Set of PR numbers whose cached payload carries
-            ``"merged": true``. A closed-without-merge PR is in
-            ``closed_refs`` but NOT in ``merged_refs``.
-        pending_count: Number of ``*.vbrief.json`` files in
-            ``vbrief/pending/``.
-        slices: Cohort records from ``vbrief/.eval/slices.jsonl`` (#1132 /
-            D13). Consulted by ``slice-wave-ready:<slice_id>:<wave>``
-            atoms; empty tuple for back-compat with pre-D13 callers.
-    """
-
-    today: date
-    closed_refs: frozenset[int] = field(default_factory=frozenset)
-    merged_refs: frozenset[int] = field(default_factory=frozenset)
-    pending_count: int = 0
-    slices: tuple[dict[str, Any], ...] = field(default_factory=tuple)
-
-
-# ---------------------------------------------------------------------------
-# Parser
-# ---------------------------------------------------------------------------
-
-_REF_CLOSED_RE = re.compile(r"^ref:closed:#(\d+)$")
-_REF_MERGED_RE = re.compile(r"^ref:merged:#(\d+)$")
-_DATE_GE_RE = re.compile(r"^date:>=(\d{4}-\d{2}-\d{2})$")
-_PENDING_GE_RE = re.compile(r"^pending-count:>=(\d+)$")
-_PENDING_LE_RE = re.compile(r"^pending-count:<=(\d+)$")
-# slice-wave-ready:<uuid>:<wave>. UUID regex matches any RFC 4122 variant
-# (any version). Wave is a positive int.
-_SLICE_WAVE_READY_RE = re.compile(
-    r"^slice-wave-ready:"
-    r"([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})"
-    r":(\d+)$"
-)
-
-# AND / OR splitter -- whitespace-required so a value like "ANDREW" in a
-# free-text field could never be misparsed as a composition operator. The
-# split is non-greedy on the first occurrence; nested forms (more than one
-# operator at the top level) are rejected explicitly by :func:`parse`.
-_COMPOSITION_RE = re.compile(r"\s+(AND|OR)\s+")
-
-
-def _parse_atomic(raw: str) -> Atomic:
-    """Parse a single atomic-condition string. Raises :class:`ResumeGrammarError`."""
-    text = raw.strip()
-    if not text:
-        raise ResumeGrammarError("empty atomic condition")
-
-    if (m := _REF_CLOSED_RE.match(text)) is not None:
-        return Atomic(kind="ref-closed", value=int(m.group(1)), raw=text)
-    if (m := _REF_MERGED_RE.match(text)) is not None:
-        return Atomic(kind="ref-merged", value=int(m.group(1)), raw=text)
-    if (m := _DATE_GE_RE.match(text)) is not None:
-        try:
-            parsed = date.fromisoformat(m.group(1))
-        except ValueError as exc:
-            raise ResumeGrammarError(
-                f"invalid date in {text!r}: {exc}"
-            ) from exc
-        return Atomic(kind="date-ge", value=parsed, raw=text)
-    if (m := _PENDING_GE_RE.match(text)) is not None:
-        return Atomic(kind="pending-count-ge", value=int(m.group(1)), raw=text)
-    if (m := _PENDING_LE_RE.match(text)) is not None:
-        return Atomic(kind="pending-count-le", value=int(m.group(1)), raw=text)
-    if (m := _SLICE_WAVE_READY_RE.match(text)) is not None:
-        wave = int(m.group(2))
-        if wave < 1:
-            raise ResumeGrammarError(
-                f"slice-wave-ready wave must be a positive int, got {wave}"
-            )
-        return Atomic(
-            kind="slice-wave-ready",
-            value=wave,
-            raw=text,
-            slice_id=m.group(1).lower(),
-        )
-
-    raise ResumeGrammarError(
-        f"unrecognised atomic condition {text!r}; "
-        "expected one of: ref:closed:#N, ref:merged:#N, date:>=YYYY-MM-DD, "
-        "pending-count:>=N, pending-count:<=N, "
-        "slice-wave-ready:<slice_id>:<wave>"
-    )
-
-
-def parse(expr: str) -> Expression:
-    """Parse ``expr`` and return an :class:`Expression` AST.
-
-    Composition rules (v1):
-
-    * Whitespace-surrounded ``AND`` or ``OR`` joins exactly two atomics.
-    * Mixing operators (``A AND B OR C``) is rejected -- v1 does not
-      define operator precedence; the operator MUST be uniform.
-    * More than one operator at the top level (``A AND B AND C``) is
-      rejected -- nested / multi-arity composition is deferred to v2.
-
-    Raises:
-        ResumeGrammarError: with an actionable message on any violation.
-    """
-    if not isinstance(expr, str):
-        raise ResumeGrammarError(
-            f"resume_on must be a string, got {type(expr).__name__}"
-        )
-    text = expr.strip()
-    if not text:
-        raise ResumeGrammarError("resume_on must be a non-empty string")
-
-    parts = _COMPOSITION_RE.split(text)
-    if len(parts) == 1:
-        atom = _parse_atomic(parts[0])
-        return Expression(op="ATOM", left=atom, right=None, raw=text)
-    if len(parts) == 3:
-        left_raw, op, right_raw = parts
-        if op not in {"AND", "OR"}:  # pragma: no cover -- regex guards this
-            raise ResumeGrammarError(
-                f"unknown composition operator {op!r}; expected AND or OR"
-            )
-        left = _parse_atomic(left_raw)
-        right = _parse_atomic(right_raw)
-        return Expression(op=op, left=left, right=right, raw=text)
-    # 5+ parts means at least two operators (regex split yields
-    # ``[lhs, op, mid, op, rhs, ...]``). v1 forbids this.
-    raise ResumeGrammarError(
-        f"resume_on supports a single top-level AND/OR in v1; got {text!r}"
-    )
-
-
-# ---------------------------------------------------------------------------
-# Evaluator
-# ---------------------------------------------------------------------------
-
-
-def _eval_atomic(atom: Atomic, ctx: ResumeContext) -> bool:
-    # ``atom.value`` is typed as ``int | date`` to accommodate both shapes the
-    # parser produces; each branch below knows the actual concrete type from
-    # the ``kind`` discriminator and casts via ``cast`` so the static type
-    # checker can see the narrowing.
-    if atom.kind == "ref-closed":
-        return cast(int, atom.value) in ctx.closed_refs
-    if atom.kind == "ref-merged":
-        return cast(int, atom.value) in ctx.merged_refs
-    if atom.kind == "date-ge":
-        return ctx.today >= cast(date, atom.value)
-    if atom.kind == "pending-count-ge":
-        return ctx.pending_count >= cast(int, atom.value)
-    if atom.kind == "pending-count-le":
-        return ctx.pending_count <= cast(int, atom.value)
-    if atom.kind == "slice-wave-ready":
-        wave = cast(int, atom.value)
-        return _slice_wave_ready(ctx, atom.slice_id, wave)
-    # Unreachable: parse() rejects unknown kinds. Defensive: a future
-    # additive atomic that lands without an evaluator branch should be a
-    # loud failure, not a silent ``False``.
-    raise ResumeGrammarError(  # pragma: no cover -- defensive
-        f"evaluator missing branch for atomic kind {atom.kind!r}"
-    )
-
-
-def _slice_wave_ready(ctx: ResumeContext, slice_id: str, wave: int) -> bool:
-    """Return True when every child of ``slice_id`` in an earlier wave is closed.
-
-    Semantics (per #1132 issue body):
-
-    * Looks up the slice record by ``slice_id`` in ``ctx.slices``.
-    * Considers only children whose ``wave`` is < ``wave``.
-    * Fires when EVERY earlier-wave child's number is in
-      ``ctx.closed_refs``.
-    * If the slice record is absent, or there are no earlier-wave
-      children (e.g. ``wave == 1``, which has no Wave-0 to gate on),
-      the atomic does NOT fire -- the resume condition is meaningless
-      and should be revised by the operator rather than silently
-      passing.
-    """
-    sid_norm = slice_id.lower()
-    record: dict[str, Any] | None = None
-    for entry in ctx.slices:
-        if not isinstance(entry, dict):
-            continue
-        candidate = entry.get("slice_id")
-        if isinstance(candidate, str) and candidate.lower() == sid_norm:
-            record = entry
-            break
-    if record is None:
-        return False
-    children = record.get("children")
-    if not isinstance(children, list):
-        return False
-    earlier: list[int] = []
-    for child in children:
-        if not isinstance(child, dict):
-            continue
-        cwave = child.get("wave")
-        cn = child.get("n")
-        if not isinstance(cwave, int) or not isinstance(cn, int):
-            continue
-        if cwave < wave:
-            earlier.append(cn)
-    if not earlier:
-        return False
-    return all(n in ctx.closed_refs for n in earlier)
-
-
-def evaluate(expr: Expression, ctx: ResumeContext) -> bool:
-    """Evaluate ``expr`` against ``ctx`` and return whether the condition fires."""
-    if expr.op == "ATOM":
-        return _eval_atomic(expr.left, ctx)
-    if expr.op == "AND":
-        if expr.right is None:  # pragma: no cover -- parse guards
-            raise ResumeGrammarError("AND expression missing right-hand atom")
-        return _eval_atomic(expr.left, ctx) and _eval_atomic(expr.right, ctx)
-    if expr.op == "OR":
-        if expr.right is None:  # pragma: no cover -- parse guards
-            raise ResumeGrammarError("OR expression missing right-hand atom")
-        return _eval_atomic(expr.left, ctx) or _eval_atomic(expr.right, ctx)
-    raise ResumeGrammarError(  # pragma: no cover -- defensive
-        f"unknown composition op {expr.op!r}"
-    )
-
-
-# ---------------------------------------------------------------------------
-# Context builder
-# ---------------------------------------------------------------------------
-
-
-def _count_pending(project_root: Path) -> int:
-    folder = project_root / "vbrief" / PENDING_LIFECYCLE_DIR
-    if not folder.is_dir():
-        return 0
-    return sum(
-        1
-        for child in folder.iterdir()
-        if child.is_file() and child.name.endswith(".vbrief.json")
-    )
-
-
-def _iter_cached_payloads(
-    project_root: Path,
-    *,
-    cache_root: Path | None = None,
-    repo: str | None = None,
-) -> Iterable[tuple[str, int, dict[str, Any]]]:
-    """Yield ``(repo, number, payload)`` for every cached issue/PR.
-
-    Walks ``<cache>/github-issue/<owner>/<repo>/<N>/raw.json``. The
-    ``repo`` filter is optional; when set, restricts to a single
-    ``owner/name`` slug (used by tests + the CLI when --repo is passed).
-    """
-    base = (cache_root or (project_root / CACHE_DIR_NAME)) / CACHE_SOURCE_GITHUB_ISSUE
-    if not base.is_dir():
-        return
-    target_owner: str | None = None
-    target_name: str | None = None
-    if repo and "/" in repo:
-        target_owner, target_name = repo.split("/", 1)
-    for owner_dir in base.iterdir():
-        if not owner_dir.is_dir():
-            continue
-        if target_owner is not None and owner_dir.name != target_owner:
-            continue
-        for repo_dir in owner_dir.iterdir():
-            if not repo_dir.is_dir():
-                continue
-            if target_name is not None and repo_dir.name != target_name:
-                continue
-            slug = f"{owner_dir.name}/{repo_dir.name}"
-            for issue_dir in repo_dir.iterdir():
-                if not issue_dir.is_dir() or not issue_dir.name.isdecimal():
-                    continue
-                raw_path = issue_dir / "raw.json"
-                if not raw_path.is_file():
-                    continue
-                try:
-                    payload = json.loads(raw_path.read_text(encoding="utf-8"))
-                except (OSError, json.JSONDecodeError):
-                    continue
-                if not isinstance(payload, dict):
-                    continue
-                try:
-                    n = int(issue_dir.name)
-                except ValueError:
-                    continue
-                yield slug, n, payload
-
-
-def build_context(
-    project_root: Path,
-    *,
-    cache_root: Path | None = None,
-    today: date | None = None,
-    repo: str | None = None,
-    slices_log_path: Path | None = None,
-) -> ResumeContext:
-    """Derive a :class:`ResumeContext` from on-disk state.
-
-    Pure-stdlib reader -- no live ``gh`` calls. ``today`` defaults to the
-    UTC calendar date (so a midnight-boundary cron run on a UTC host
-    evaluates ``date:>=`` consistently). ``slices_log_path`` overrides
-    the default ``vbrief/.eval/slices.jsonl`` location for tests; the
-    canonical path is used otherwise. When :mod:`slice_record` is not
-    importable (pre-D13 slim checkout) the slices tuple is empty and
-    ``slice-wave-ready`` atoms cannot fire.
-    """
-    today_resolved = today or datetime.now(UTC).date()
-    closed: set[int] = set()
-    merged: set[int] = set()
-    for _slug, n, payload in _iter_cached_payloads(
-        project_root, cache_root=cache_root, repo=repo
-    ):
-        state = payload.get("state")
-        if isinstance(state, str) and state.lower() == "closed":
-            closed.add(n)
-        # ``merged`` is a PR-only field; ``"mergedAt"`` is the canonical
-        # marker emitted by ``gh pr view --json``, but plain GitHub REST
-        # uses ``"merged": true``. Accept both so the evaluator works
-        # against either cache writer.
-        if payload.get("merged") is True or payload.get("mergedAt"):
-            merged.add(n)
-    slices: tuple[dict[str, Any], ...] = ()
-    if slice_record is not None:
-        try:
-            records = slice_record.read_all(path=slices_log_path)
-        except Exception as exc:  # noqa: BLE001 -- best-effort; pre-D13 fallback
-            LOG.warning("slice_record.read_all failed: %s", exc)
-            records = []
-        slices = tuple(r for r in records if isinstance(r, dict))
-    return ResumeContext(
-        today=today_resolved,
-        closed_refs=frozenset(closed),
-        merged_refs=frozenset(merged),
-        pending_count=_count_pending(project_root),
-        slices=slices,
-    )
-
-
-# ---------------------------------------------------------------------------
-# Evaluator orchestration -- the audit-log writer
-# ---------------------------------------------------------------------------
-
-
-def _now_iso() -> str:
-    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
-
-
-def _open_defer_entries(
-    entries: list[dict[str, Any]],
-) -> list[dict[str, Any]]:
-    """Return the open ``defer`` entries -- those not yet superseded.
-
-    An entry is "open" when:
-
-    * It is a ``defer`` decision with a non-null ``resume_on`` field, AND
-    * No later (timestamp >) entry for the same ``(repo, issue_number)``
-      has ``decision`` in ``{accept, reject, mark-duplicate, reset,
-      resume-eligible}``.
-
-    The ``resume-eligible`` self-supersession is what guarantees
-    idempotency: once we've emitted a ``resume-eligible`` row for a
-    defer, the defer is no longer "open" from this function's
-    perspective and a re-evaluation skips it.
-    """
-    # Group by (repo, issue_number) so we can pick the latest entry per
-    # issue and decide supersession.
-    by_issue: dict[tuple[str, int], list[dict[str, Any]]] = {}
-    for entry in entries:
-        if not isinstance(entry, dict):
-            continue
-        repo = entry.get("repo")
-        number = entry.get("issue_number")
-        if not isinstance(repo, str) or not isinstance(number, int):
-            continue
-        by_issue.setdefault((repo, number), []).append(entry)
-
-    superseding = {"accept", "reject", "mark-duplicate", "reset", RESUME_ELIGIBLE_DECISION}
-    open_defers: list[dict[str, Any]] = []
-    for rows in by_issue.values():
-        # Sort by timestamp ascending so the last entry is most recent.
-        rows.sort(key=lambda r: str(r.get("timestamp", "")))
-        target_defer: dict[str, Any] | None = None
-        superseded = False
-        for row in rows:
-            decision = row.get("decision")
-            if decision == "defer":
-                target_defer = row
-                superseded = False
-            elif decision in superseding and target_defer is not None:
-                # Same-issue successor wipes the open-defer candidacy.
-                # ``reset`` re-opens to untriaged (handled by the
-                # decision != "defer" branch -- target_defer stays None
-                # until a new defer lands).
-                superseded = True
-                target_defer = None
-        if target_defer is None or superseded:
-            continue
-        if not target_defer.get("resume_on"):
-            continue
-        open_defers.append(target_defer)
-    return open_defers
-
-
-def evaluate_resume_eligibility(
-    project_root: Path,
-    *,
-    cache_root: Path | None = None,
-    audit_log_path: Path | None = None,
-    today: date | None = None,
-    repo: str | None = None,
-    log_module: Any | None = None,
-    new_id: Any | None = None,
-    now_iso: Any | None = None,
-) -> list[dict[str, Any]]:
-    """Evaluate every open defer with ``resume_on`` and append firings.
-
-    Returns the list of newly-appended ``resume-eligible`` entries (may
-    be empty). Skipping conditions:
-
-    * No ``resume_on`` field on the defer -- pre-D3 entries pass through.
-    * Condition does not fire against the current :class:`ResumeContext`.
-    * A ``resume-eligible`` entry already exists referencing the defer's
-      ``decision_id`` -- the marker is idempotent.
-
-    The ``log_module`` / ``new_id`` / ``now_iso`` hooks let tests inject
-    fakes without monkeypatching module-level state. Production callers
-    leave them as ``None`` so the canonical ``candidates_log.append``
-    seam is used.
-    """
-    log = log_module if log_module is not None else candidates_log
-    if log is None:
-        # No audit-log writer available -- nothing to do. Production
-        # bootstrap lands the writer; this branch is for slim test
-        # checkouts (mirrors the pattern in scripts/triage_actions.py).
-        return []
-    new_decision_id = new_id or getattr(log, "new_decision_id", None)
-    if not callable(new_decision_id):  # pragma: no cover -- defensive
-        import uuid as _uuid
-
-        new_decision_id = lambda: str(_uuid.uuid4())  # noqa: E731
-    timestamp_fn = now_iso or _now_iso
-
-    entries = list(log.read_all(repo=repo, path=audit_log_path))
-    open_defers = _open_defer_entries(entries)
-    if not open_defers:
-        return []
-
-    ctx = build_context(
-        project_root, cache_root=cache_root, today=today, repo=repo
-    )
-
-    appended: list[dict[str, Any]] = []
-    for defer_entry in open_defers:
-        expression_text = defer_entry.get("resume_on")
-        if not isinstance(expression_text, str):
-            continue
-        try:
-            ast = parse(expression_text)
-        except ResumeGrammarError as exc:
-            LOG.warning(
-                "skipping defer #%s (%s): malformed resume_on %r (%s)",
-                defer_entry.get("issue_number"),
-                defer_entry.get("repo"),
-                expression_text,
-                exc,
-            )
-            continue
-        if not evaluate(ast, ctx):
-            continue
-        new_entry: dict[str, Any] = {
-            "decision_id": str(new_decision_id()),
-            "timestamp": timestamp_fn(),
-            "repo": str(defer_entry["repo"]),
-            "issue_number": int(defer_entry["issue_number"]),
-            "decision": RESUME_ELIGIBLE_DECISION,
-            "actor": EVALUATOR_ACTOR,
-            "prior_decision_id": str(defer_entry["decision_id"]),
-            "reason": f"resume_on fired: {expression_text}",
-        }
-        try:
-            log.append(new_entry, path=audit_log_path) if audit_log_path else log.append(new_entry)
-        except TypeError:
-            # Older test fakes accept (entry) only -- fall back without path kw.
-            log.append(new_entry)
-        except Exception as exc:  # noqa: BLE001 -- best-effort; surface failure
-            LOG.warning(
-                "candidates_log.append failed for defer #%s: %s",
-                defer_entry.get("issue_number"),
-                exc,
-            )
-            continue
-        appended.append(new_entry)
-    return appended
-
-
-# ---------------------------------------------------------------------------
-# Best-effort UTF-8 stdout (CLI consumers print expressions verbatim)
-# ---------------------------------------------------------------------------
-
-for _stream in (sys.stdout, sys.stderr):
-    if hasattr(_stream, "reconfigure"):  # pragma: no cover -- env hook
-        with contextlib.suppress(AttributeError, ValueError):
-            _stream.reconfigure(encoding="utf-8", errors="replace")
-
-
-__all__ = [
-    "Atomic",
-    "EVALUATOR_ACTOR",
-    "Expression",
-    "RESUME_ELIGIBLE_DECISION",
-    "ResumeContext",
-    "ResumeGrammarError",
-    "build_context",
-    "evaluate",
-    "evaluate_resume_eligibility",
-    "parse",
-]