@deftai/directive-content 0.59.0 → 0.60.0

package/scripts/preflight_cache.py

@@ -1,974 +0,0 @@
-#!/usr/bin/env python3
-"""preflight_cache.py -- detection-bound cache-freshness gate (#1127, D5 of #1119).
-
-Pure stdlib, cross-platform. Invoked from:
-
-- ``deft verify:cache-fresh`` (aggregated into ``task check``)
-- Dispatcher pre-``start_agent`` invocations -- the dispatcher MUST run
-  ``deft verify:cache-fresh --for-issue <N>`` before any ``start_agent``
-  and refuse dispatch on any non-zero exit (see
-  ``templates/agent-prompt-preamble.md`` § 12).
-
-Mirrors ``scripts/preflight_branch.py`` (#747) in shape: pure-stdlib so it
-can run from a fresh git hook or a minimal CI runner before ``uv sync``
-has produced an environment.
-
-Exit codes (three-state):
-
-- ``0`` -- cache fresh AND no blocking defer conditions.
-- ``1`` -- cache stale OR blocking conditions found; prints remediation
-  to stderr (names ``deft triage:bootstrap`` and ``deft cache:fetch-all``
-  per the issue body).
-- ``2`` -- config error: ``.deft-cache/`` missing entirely, or
-  ``vbrief/.eval/candidates.jsonl`` missing. The config-error class is
-  distinct from "cache stale" so a dispatcher can distinguish a never-
-  -bootstrapped project (operator runs ``deft triage:bootstrap``) from
-  a stale-cache project (operator runs ``deft cache:fetch-all``).
-
-State machine (#1240):
-
-Three user-visible states the OK message must distinguish post-#1240
-because ``deft triage:bootstrap`` now seeds an empty audit log:
-
-1. **No cache yet** -- ``.deft-cache/<source>/`` absent. This is the
-   never-bootstrapped state; the gate exits 2 (or 0 + bootstrap-state
-   message when ``--allow-missing-bootstrap`` is passed).
-2. **Cache present + audit log empty** -- consumer just ran
-   ``deft triage:bootstrap`` but has not yet executed any triage
-   action. The gate exits 0 with a ``fresh bootstrap, no triage
-   actions yet`` message. Pre-#1240 this state was unreachable because
-   bootstrap left the audit log absent -- the gate fell through to
-   the config-error branch and printed ``treating as bootstrap state``
-   on a freshly-bootstrapped consumer.
-3. **Cache present + audit log non-empty** -- canonical fresh state.
-   The gate exits 0 with the ``actively triaging`` message.
-
-Subscription-awareness (#1131 / D12 of #1119):
-
-The freshness check is scoped to the consumer's
-``plan.policy.triageScope[]`` subscription -- read via the D12 surface
-:mod:`triage_scope` -- so a consumer with a tightened scope is not
-gated by stale entries the operator has explicitly chosen not to track.
-When ``--for-issue <N>`` is given the gate ALSO verifies the issue is
-in scope; an out-of-scope issue exits 1 with a pointer to
-``deft triage:scope``.
-
-Override paths:
-
-- ``--allow-stale`` -- exit 0 with an audit-trail warning on stderr.
-  Per-shell only; never persisted. Same shape as
-  ``DEFT_ALLOW_DEFAULT_BRANCH_COMMIT`` from #747.
-- ``--max-age-hours N`` / ``DEFT_CACHE_MAX_AGE_HOURS=N`` -- override the
-  default 24h freshness window (env honoured when the flag is absent).
-"""
-
-from __future__ import annotations
-
-import argparse
-import contextlib
-import json
-import os
-import subprocess
-import sys
-from collections.abc import Iterable
-from dataclasses import dataclass
-from datetime import UTC, datetime, timedelta
-from pathlib import Path
-from typing import Any
-
-# Make sibling ``scripts`` modules importable when invoked via
-# ``python scripts/preflight_cache.py`` from any working directory.
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-
-# UTF-8 self-reconfigure (#814) -- error / OK messages include the ✓ /
-# ⚠ / ❌ glyphs that cp1252 cannot encode.
-for _stream in (sys.stdout, sys.stderr):
-    if hasattr(_stream, "reconfigure"):
-        with contextlib.suppress(AttributeError, ValueError):
-            _stream.reconfigure(encoding="utf-8", errors="replace")
-
-
-# ---------------------------------------------------------------------------
-# Public constants
-# ---------------------------------------------------------------------------
-
-#: Cache directory name (mirrors ``scripts/cache.py::DEFAULT_CACHE_ROOT``).
-CACHE_DIR_NAME: str = ".deft-cache"
-
-#: Source the gate inspects. v1 ships ``github-issue`` only -- the same
-#: scoping decision documented in #1127 "Not in scope".
-DEFAULT_SOURCE: str = "github-issue"
-
-#: Candidates audit log (mirrors ``scripts/candidates_log.py::DEFAULT_LOG_PATH``).
-CANDIDATES_RELPATH: Path = Path("vbrief") / ".eval" / "candidates.jsonl"
-
-#: Default freshness window in hours; configurable via flag / env.
-DEFAULT_MAX_AGE_HOURS: int = 24
-
-#: Env var override for the freshness window (parsed as int hours).
-ENV_MAX_AGE_HOURS: str = "DEFT_CACHE_MAX_AGE_HOURS"
-
-#: Env var honoured for repo inference when --repo is absent (mirrors
-#: ``scripts/triage_bootstrap.py::DEFT_TRIAGE_REPO``).
-ENV_TRIAGE_REPO: str = "DEFT_TRIAGE_REPO"
-
-#: Decision verdict required for ``--for-issue`` to clear the gate. Any
-#: other latest decision (``defer`` / ``reject`` / ``needs-ac`` /
-#: ``mark-duplicate`` / ``reset``) blocks dispatch.
-REQUIRED_DECISION: str = "accept"
-
-
-# ---------------------------------------------------------------------------
-# Result dataclass + helpers
-# ---------------------------------------------------------------------------
-
-
-@dataclass(frozen=True)
-class GateResult:
-    """Pure-data result of :func:`evaluate`. ``code`` is the exit code."""
-
-    code: int
-    message: str
-
-
-def _utc_now() -> datetime:
-    return datetime.now(UTC)
-
-
-def _parse_iso(stamp: str) -> datetime:
-    """Parse an ISO-8601 timestamp; accepts trailing ``Z``."""
-    text = stamp.strip()
-    if text.endswith("Z"):
-        text = text[:-1] + "+00:00"
-    dt = datetime.fromisoformat(text)
-    if dt.tzinfo is None:
-        dt = dt.replace(tzinfo=UTC)
-    return dt
-
-
-# ---------------------------------------------------------------------------
-# Repo discovery
-# ---------------------------------------------------------------------------
-
-
-def _infer_repo_from_git(project_root: Path) -> str | None:
-    """Best-effort: read ``git remote get-url origin`` inside ``project_root``.
-
-    Returns ``"owner/name"`` on success, ``None`` otherwise. A stuck git
-    proxy (corporate VPN re-auth) is bounded by a 10s timeout so the
-    gate never hangs the dispatcher.
-    """
-    try:
-        proc = subprocess.run(
-            ["git", "remote", "get-url", "origin"],
-            cwd=str(project_root),
-            capture_output=True,
-            text=True,
-            check=False,
-            timeout=10,
-        )
-    except (FileNotFoundError, subprocess.TimeoutExpired):
-        return None
-    if proc.returncode != 0:
-        return None
-    url = proc.stdout.strip()
-    if not url:
-        return None
-    # github.com/owner/name(.git) -- accepts ssh / https / git protocol.
-    cleaned = url.rstrip("/")
-    if cleaned.endswith(".git"):
-        cleaned = cleaned[: -len(".git")]
-    if "github.com" not in cleaned:
-        return None
-    tail = cleaned.split("github.com", 1)[1].lstrip(":/")
-    parts = tail.split("/")
-    if len(parts) >= 2 and parts[0] and parts[1]:
-        return f"{parts[0]}/{parts[1]}"
-    return None
-
-
-def _scan_cache_for_single_repo(cache_root: Path, source: str) -> str | None:
-    """Return ``owner/name`` when the cache contains exactly one repo, else None."""
-    base = cache_root / source
-    if not base.is_dir():
-        return None
-    pairs: list[tuple[str, str]] = []
-    for owner_dir in sorted(base.iterdir()):
-        if not owner_dir.is_dir():
-            continue
-        for repo_dir in sorted(owner_dir.iterdir()):
-            if repo_dir.is_dir():
-                pairs.append((owner_dir.name, repo_dir.name))
-    if len(pairs) == 1:
-        owner, name = pairs[0]
-        return f"{owner}/{name}"
-    return None
-
-
-def _resolve_repo(
-    project_root: Path,
-    cache_root: Path,
-    source: str,
-    *,
-    explicit: str | None,
-) -> str | None:
-    """Resolve the repo slug in priority order: flag > env > git > single-cache-repo."""
-    if explicit:
-        return explicit
-    env_repo = os.environ.get(ENV_TRIAGE_REPO, "").strip()
-    if env_repo:
-        return env_repo
-    inferred = _infer_repo_from_git(project_root)
-    if inferred:
-        return inferred
-    return _scan_cache_for_single_repo(cache_root, source)
-
-
-# ---------------------------------------------------------------------------
-# Cache scanning
-# ---------------------------------------------------------------------------
-
-
-def _iter_meta_paths(cache_root: Path, source: str, repo: str) -> Iterable[Path]:
-    """Yield each ``meta.json`` path under ``<cache_root>/<source>/<repo>/*/``."""
-    if "/" not in repo:
-        return
-    owner, name = repo.split("/", 1)
-    repo_dir = cache_root / source / owner / name
-    if not repo_dir.is_dir():
-        return
-    for entry in sorted(repo_dir.iterdir()):
-        if not entry.is_dir():
-            continue
-        meta = entry / "meta.json"
-        if meta.is_file():
-            yield meta
-
-
-def _read_meta(meta_path: Path) -> dict[str, Any] | None:
-    try:
-        data = json.loads(meta_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return None
-    return data if isinstance(data, dict) else None
-
-
-def _read_raw_issue(meta_path: Path) -> dict[str, Any] | None:
-    """Read the sibling ``raw.json`` and return the parsed payload."""
-    raw_path = meta_path.parent / "raw.json"
-    if not raw_path.is_file():
-        return None
-    try:
-        data = json.loads(raw_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return None
-    return data if isinstance(data, dict) else None
-
-
-# ---------------------------------------------------------------------------
-# Subscription-aware filtering (D12 / #1131)
-# ---------------------------------------------------------------------------
-
-
-def _load_triage_scope_module() -> Any | None:
-    """Lazy-load :mod:`triage_scope`; returns ``None`` if missing.
-
-    D12 (#1131) is the upstream surface. The gate degrades gracefully to
-    "no subscription filter" when the module is absent so a partial
-    install / pre-D12 branch still gets the cache-freshness check.
-    """
-    try:
-        import triage_scope  # type: ignore[import-not-found]
-
-        return triage_scope
-    except ImportError:
-        return None
-
-
-def _resolve_scope_rules(project_root: Path) -> list[dict[str, Any]] | None:
-    """Return the effective ``plan.policy.triageScope[]`` rule list.
-
-    Returns ``None`` when :mod:`triage_scope` is not importable; in that
-    case the caller skips subscription filtering.
-    """
-    mod = _load_triage_scope_module()
-    if mod is None:
-        return None
-    try:
-        rules = mod.resolve_scope_rules(project_root)
-    except Exception:  # noqa: BLE001 -- defensive, subscription is optional
-        return None
-    return list(rules) if isinstance(rules, list) else None
-
-
-def _issue_in_scope(
-    rules: list[dict[str, Any]] | None,
-    issue: dict[str, Any],
-    *,
-    project_root: Path,
-) -> bool:
-    """True when ``issue`` is matched by ``rules`` (or rules are absent)."""
-    if not rules:
-        return True
-    mod = _load_triage_scope_module()
-    if mod is None:
-        return True
-    try:
-        matched = mod.evaluate_rules(rules, [issue])
-    except Exception:  # noqa: BLE001 -- defensive fallthrough
-        return True
-    if not isinstance(matched, list):
-        return True
-    target_number = issue.get("number")
-    return any(
-        isinstance(m, dict) and m.get("number") == target_number for m in matched
-    )
-
-
-def _filter_scoped_meta_paths(
-    meta_paths: list[Path],
-    rules: list[dict[str, Any]] | None,
-    *,
-    open_milestones_fetcher: Any = None,
-) -> list[Path]:
-    """Filter ``meta_paths`` to those whose raw.json matches the scope rules.
-
-    #1424: evaluate the rule set ONCE over the whole cache rather than
-    once per cached entry. The per-issue fan-out used to call
-    ``evaluate_rules(rules, [issue])`` N times; because
-    ``evaluate_rules`` builds (and memoizes only within a single call) a
-    fresh open-milestones resolver, a ``milestone {is-open: true}`` rule
-    re-fetched the upstream snapshot once per issue -- an O(N) network
-    fan-out (~92s on a 500-entry cache). Batching collapses that to a
-    single ``evaluate_rules`` call (one milestone fetch) with identical
-    semantics, mirroring the proven fetch-once shape in
-    ``triage_scope_drift.compute_drift``.
-
-    Matched entries are resolved by OBJECT IDENTITY (``id(issue)``), not
-    by issue number: ``evaluate_rules`` dedups via
-    ``matched.setdefault(_issue_number(issue), issue)`` and returns the
-    very issue dicts passed in, so number-keying here would risk
-    collisions or drop entries whose ``number`` is missing/None.
-
-    ``open_milestones_fetcher`` is forwarded to ``evaluate_rules`` for
-    the ``milestone {is-open: true}`` variant; production leaves it
-    ``None`` (the default ``gh api`` fetcher fires once), tests inject a
-    counting closure to assert the at-most-once contract.
-    """
-    if not rules:
-        return meta_paths
-    mod = _load_triage_scope_module()
-    if mod is None:
-        # Subscription module unavailable -> no filtering (over-include).
-        return meta_paths
-
-    all_issues: list[dict[str, Any]] = []
-    issue_id_to_meta: dict[int, Path] = {}
-    # Entries whose raw.json is missing or unparseable are kept: the
-    # freshness check is the load-bearing signal and we'd rather
-    # over-include than mask a stale cache.
-    keep: set[Path] = set()
-    for meta_path in meta_paths:
-        raw = _read_raw_issue(meta_path)
-        if raw is None:
-            keep.add(meta_path)
-            continue
-        all_issues.append(raw)
-        issue_id_to_meta[id(raw)] = meta_path
-
-    if all_issues:
-        try:
-            matched = mod.evaluate_rules(
-                rules, all_issues, open_milestones_fetcher=open_milestones_fetcher
-            )
-        except Exception:  # noqa: BLE001 -- defensive: over-include on failure
-            return meta_paths
-        if not isinstance(matched, list):
-            return meta_paths
-        for issue in matched:
-            meta_path = issue_id_to_meta.get(id(issue))
-            if meta_path is not None:
-                keep.add(meta_path)
-
-    # Preserve the original meta_paths ordering.
-    return [meta_path for meta_path in meta_paths if meta_path in keep]
-
-
-# ---------------------------------------------------------------------------
-# candidates.jsonl helpers
-# ---------------------------------------------------------------------------
-
-
-def _candidates_path(project_root: Path) -> Path:
-    return project_root / CANDIDATES_RELPATH
-
-
-def _latest_decision_for_issue(
-    candidates: Path, *, repo: str, issue_number: int
-) -> dict[str, Any] | None:
-    """Return the most recent decision dict for ``(repo, issue_number)``.
-
-    Mirrors :func:`scripts.candidates_log.latest_decision` without taking
-    a hard dependency on the module (pure stdlib here so the gate runs
-    on a fresh checkout).
-    """
-    if not candidates.is_file():
-        return None
-    rows: list[dict[str, Any]] = []
-    try:
-        with candidates.open(encoding="utf-8") as fh:
-            for raw_line in fh:
-                line = raw_line.strip()
-                if not line:
-                    continue
-                try:
-                    obj = json.loads(line)
-                except json.JSONDecodeError:
-                    continue
-                if not isinstance(obj, dict):
-                    continue
-                if obj.get("repo") != repo:
-                    continue
-                if obj.get("issue_number") != issue_number:
-                    continue
-                rows.append(obj)
-    except OSError:
-        return None
-    if not rows:
-        return None
-    rows.sort(key=lambda r: r.get("timestamp", ""))
-    return rows[-1]
-
-
-# ---------------------------------------------------------------------------
-# Freshness window resolution
-# ---------------------------------------------------------------------------
-
-
-def _resolve_max_age_hours(explicit: int | None) -> int:
-    if explicit is not None:
-        return max(0, int(explicit))
-    raw = os.environ.get(ENV_MAX_AGE_HOURS, "").strip()
-    if not raw:
-        return DEFAULT_MAX_AGE_HOURS
-    try:
-        parsed = int(raw)
-    except ValueError:
-        return DEFAULT_MAX_AGE_HOURS
-    return max(0, parsed)
-
-
-def is_fetched_at_stale(
-    fetched_at: str | None,
-    *,
-    max_age_hours: int | None = None,
-    now: datetime | None = None,
-) -> bool:
-    """Return True when a cache entry's ``fetched_at`` is older than the window.
-
-    Pure, side-effect-free predicate shared with the #1476 triage:queue
-    defensive stale-state path so the freshness window is resolved the
-    same way everywhere (flag / ``DEFT_CACHE_MAX_AGE_HOURS`` env / 24h
-    default, via :func:`_resolve_max_age_hours`).
-
-    A missing / empty / unparseable ``fetched_at`` is treated as stale
-    (the cache cannot vouch for the entry's age). When the resolved
-    window is ``0`` (freshness disabled) nothing is stale. A negative
-    age (clock skew -- ``fetched_at`` in the future) is clamped to
-    fresh.
-    """
-    if not isinstance(fetched_at, str) or not fetched_at.strip():
-        return True
-    max_age_h = _resolve_max_age_hours(max_age_hours)
-    if max_age_h <= 0:
-        return False
-    try:
-        fetched = _parse_iso(fetched_at)
-    except ValueError:
-        return True
-    age_h = ((now or _utc_now()) - fetched).total_seconds() / 3600.0
-    return age_h > max_age_h
-
-
-# ---------------------------------------------------------------------------
-# Core evaluator
-# ---------------------------------------------------------------------------
-
-
-_REMEDIATION_STALE = (
-    "  Remediation:\n"
-    "    deft triage:bootstrap         # full re-populate, or\n"
-    "    deft cache:fetch-all -- --source github-issue --repo <OWNER/NAME>\n"
-    "  Override (audited): --allow-stale (or DEFT_CACHE_MAX_AGE_HOURS=<N>)."
-)
-
-
-def evaluate(
-    project_root: Path,
-    *,
-    source: str = DEFAULT_SOURCE,
-    repo: str | None = None,
-    max_age_hours: int | None = None,
-    for_issue: int | None = None,
-    allow_stale: bool = False,
-    allow_missing_bootstrap: bool = False,
-    now: datetime | None = None,
-) -> GateResult:
-    """Pure-function gate. See module docstring for exit-code semantics.
-
-    Separated from :func:`main` so tests drive every branch without
-    ``capsys`` plumbing or argv leak.
-
-    ``allow_missing_bootstrap`` mirrors ``preflight_branch.py``'s
-    ``--allow-missing-project-definition`` bootstrap escape: when
-    ``.deft-cache/`` or ``vbrief/.eval/candidates.jsonl`` is missing the
-    gate returns exit 0 with a friendly info message instead of exit 2.
-    The framework repo's own ``task check`` uses this so a fresh
-    checkout that has not yet run ``deft triage:bootstrap`` is not
-    gated by its own cache-freshness verb. Consumers leave the flag
-    OFF so the gate fails loudly when their cache is missing.
-    """
-    cache_root = project_root / CACHE_DIR_NAME
-    candidates = _candidates_path(project_root)
-    max_age_h = _resolve_max_age_hours(max_age_hours)
-    now_dt = now or _utc_now()
-
-    # --- Step 1: cache directory existence (config-error class) -----------
-    source_dir = cache_root / source
-    if not cache_root.is_dir() or not source_dir.is_dir():
-        if allow_missing_bootstrap and for_issue is None:
-            return GateResult(
-                0,
-                (
-                    f"✓ deft cache-fresh: .deft-cache/{source}/ absent and "
-                    "--allow-missing-bootstrap was passed -- treating as "
-                    "bootstrap state (consumer runs `deft triage:bootstrap` "
-                    "to opt in)."
-                ),
-            )
-        msg = (
-            f"❌ deft cache-fresh: .deft-cache/{source}/ not present under "
-            f"{project_root}. The triage cache has not been populated.\n"
-            "  Recovery: run `deft triage:bootstrap` (idempotent installer)\n"
-            "             or `deft cache:fetch-all -- --source "
-            f"{source} --repo OWNER/NAME`."
-        )
-        return GateResult(2, msg)
-
-    # --- Step 2: candidates.jsonl readable (config-error class) -----------
-    if not candidates.is_file():
-        if allow_missing_bootstrap and for_issue is None:
-            return GateResult(
-                0,
-                (
-                    f"✓ deft cache-fresh: {candidates.relative_to(project_root)} "
-                    "absent and --allow-missing-bootstrap was passed -- "
-                    "treating as bootstrap state."
-                ),
-            )
-        msg = (
-            f"❌ deft cache-fresh: {candidates} missing.\n"
-            "  Recovery: run `deft triage:bootstrap` to backfill the audit\n"
-            "             log, or accept at least one candidate via\n"
-            "             `deft triage:accept`."
-        )
-        return GateResult(2, msg)
-
-    # --- Step 3: repo resolution -----------------------------------------
-    resolved_repo = _resolve_repo(project_root, cache_root, source, explicit=repo)
-    if not resolved_repo:
-        msg = (
-            "❌ deft cache-fresh: cannot determine owner/repo. Pass --repo "
-            "OWNER/NAME, set DEFT_TRIAGE_REPO, or run inside a git checkout "
-            "whose `origin` is a github.com remote."
-        )
-        return GateResult(2, msg)
-
-    meta_paths = list(_iter_meta_paths(cache_root, source, resolved_repo))
-    if not meta_paths:
-        msg = (
-            "❌ deft cache-fresh: no cached entries under "
-            f".deft-cache/{source}/{resolved_repo}/.\n"
-            "  Recovery: `deft cache:fetch-all -- --source "
-            f"{source} --repo {resolved_repo}`."
-        )
-        return GateResult(2, msg)
-
-    # --- Step 4: subscription filter (#1131) -----------------------------
-    scope_rules = _resolve_scope_rules(project_root)
-    scoped_meta_paths = _filter_scoped_meta_paths(meta_paths, scope_rules)
-    # #1245: distinguish a ``backfill-only cache`` state (the cache
-    # contains entries but none currently match the active subscription,
-    # AND the consumer has emitted at least one triage decision
-    # -- including ``triage:bootstrap``'s backfilled ``accept`` history
-    # rows) from a genuine misconfiguration (no in-scope cached entries
-    # AND no triage activity). The backfill-only state is the expected
-    # post-bootstrap shape on a repo whose currently-cached open issues
-    # do not happen to match the operator's narrow subscription; the
-    # session-start gate should pass so the pre-``start_agent`` gate
-    # stack composes cleanly. Downstream ``--for-issue`` dispatch still
-    # enforces per-issue scope + decision via :func:`_gate_for_issue`,
-    # so this relaxation only affects the cache-wide session check.
-    backfill_only_cache = False
-    if not scoped_meta_paths:
-        audit_state = _audit_log_state(candidates)
-        if audit_state == "populated":
-            # Fall through to Step 5's freshness window using the FULL
-            # ``meta_paths`` (not the empty scoped list) so a stale
-            # cache still fails loudly even when every entry is out
-            # of subscription. The Step 6 OK message uses the
-            # ``backfill_only_cache`` flag to emit a state-aware line.
-            backfill_only_cache = True
-            scoped_meta_paths = meta_paths
-        else:
-            msg = (
-                "❌ deft cache-fresh: every cached entry is outside the active "
-                "plan.policy.triageScope[] subscription, and the audit log "
-                "is empty (no triage decisions yet).\n"
-                "  Recovery: widen the subscription (see "
-                "`deft triage:scope --list`), repopulate via "
-                "`deft cache:fetch-all`, or accept at least one candidate "
-                "via `deft triage:accept` once the cache has matching entries."
-            )
-            if allow_stale:
-                # Mirror the Step 5 stale-cache pattern: --allow-stale
-                # MUST NOT silently paper over a defer/reject/missing
-                # --for-issue decision. Run the per-issue gate FIRST
-                # and propagate any refusal; only fall through to the
-                # allow-stale exit 0 when the per-issue check is clean
-                # (or no --for-issue was passed).
-                if for_issue is not None:
-                    for_issue_result = _gate_for_issue(
-                        resolved_repo,
-                        for_issue,
-                        candidates=candidates,
-                        scope_rules=scope_rules,
-                        source_dir=source_dir,
-                        project_root=project_root,
-                    )
-                    if for_issue_result.code != 0:
-                        return for_issue_result
-                return GateResult(
-                    0,
-                    (
-                        "⚠ deft cache-fresh: --allow-stale honoured but every "
-                        "cached entry is out of scope; downstream tooling may "
-                        "still refuse work."
-                    ),
-                )
-            return GateResult(1, msg)
-
-    # --- Step 5: freshness window ----------------------------------------
-    max_fetched: datetime | None = None
-    max_meta_path: Path | None = None
-    for meta_path in scoped_meta_paths:
-        meta = _read_meta(meta_path)
-        if not meta:
-            continue
-        stamp = meta.get("fetched_at")
-        if not isinstance(stamp, str) or not stamp:
-            continue
-        try:
-            fetched = _parse_iso(stamp)
-        except ValueError:
-            continue
-        if max_fetched is None or fetched > max_fetched:
-            max_fetched = fetched
-            max_meta_path = meta_path
-
-    if max_fetched is None:
-        msg = (
-            "❌ deft cache-fresh: no parseable `fetched_at` in any cached "
-            "meta.json. The cache may be corrupted.\n"
-            "  Recovery: `deft cache:fetch-all -- --source "
-            f"{source} --repo {resolved_repo}`."
-        )
-        return GateResult(2, msg)
-
-    age = now_dt - max_fetched
-    if age < timedelta(0):
-        age = timedelta(0)
-    age_h = age.total_seconds() / 3600.0
-
-    stale = max_age_h > 0 and age_h > max_age_h
-
-    if stale and allow_stale:
-        warning = (
-            "⚠ deft cache-fresh: --allow-stale honoured; cache is "
-            f"{age_h:.1f}h old (max-age={max_age_h}h). Downstream tooling "
-            "may still refuse work."
-        )
-        # Still run the --for-issue gate so --allow-stale does not silently
-        # paper over a defer/reject decision.
-        if for_issue is not None:
-            for_issue_result = _gate_for_issue(
-                resolved_repo,
-                for_issue,
-                candidates=candidates,
-                scope_rules=scope_rules,
-                source_dir=source_dir,
-                project_root=project_root,
-            )
-            if for_issue_result.code != 0:
-                return for_issue_result
-        return GateResult(0, warning)
-
-    if stale:
-        msg = (
-            f"❌ deft cache-fresh: cache is {age_h:.1f}h old "
-            f"(max-age={max_age_h}h); newest entry "
-            f"{max_meta_path.relative_to(project_root) if max_meta_path else '?'}.\n"
-            f"{_REMEDIATION_STALE}"
-        )
-        return GateResult(1, msg)
-
-    # --- Step 6: --for-issue ---------------------------------------------
-    if for_issue is not None:
-        for_issue_result = _gate_for_issue(
-            resolved_repo,
-            for_issue,
-            candidates=candidates,
-            scope_rules=scope_rules,
-            source_dir=source_dir,
-            project_root=project_root,
-        )
-        if for_issue_result.code != 0:
-            return for_issue_result
-
-    # #1240: distinguish "fresh bootstrap, no triage actions yet" from
-    # "actively triaging". A zero-length audit log indicates the consumer
-    # just ran ``deft triage:bootstrap`` (step 5 seeded the empty file)
-    # but has not yet emitted any triage decision; the gate is still
-    # clean but the language acknowledges the operator's mental state.
-    # #1245: the ``backfill_only_cache`` flag set during Step 4 supplies
-    # a third state -- the cache holds entries but none match the active
-    # subscription, AND the audit log is populated (consumer is actively
-    # triaging). The gate passes so downstream tooling can run; the
-    # message names the state so the operator is not surprised that
-    # ``triage:queue`` etc. show zero in-scope rows.
-    audit_state = _audit_log_state(candidates)
-    if backfill_only_cache:
-        state_phrase = (
-            "backfill-only cache (no entries match "
-            "plan.policy.triageScope[]; audit log populated)"
-        )
-        in_scope_count = 0
-    elif audit_state == "empty":
-        state_phrase = "fresh bootstrap, no triage actions yet"
-        in_scope_count = len(scoped_meta_paths)
-    else:
-        state_phrase = "actively triaging"
-        in_scope_count = len(scoped_meta_paths)
-    msg = (
-        f"✓ deft cache-fresh: {resolved_repo} -- {in_scope_count} entry/ies "
-        f"in scope; newest fetched {age_h:.1f}h ago (max-age={max_age_h}h); "
-        f"{state_phrase}."
-    )
-    if for_issue is not None:
-        msg += f" Issue #{for_issue} latest decision = accept; in subscription scope."
-    return GateResult(0, msg)
-
-
-def _audit_log_state(candidates: Path) -> str:
-    """Return one of ``"empty"`` / ``"populated"`` (#1240).
-
-    A zero-length file (post-#1240 bootstrap seed) is ``empty``; any
-    file that parses at least one non-blank line is ``populated``.
-    Errors reading the file fall back to ``empty`` so a corrupted
-    audit log doesn't claim the consumer is actively triaging.
-    """
-    try:
-        if candidates.stat().st_size == 0:
-            return "empty"
-    except OSError:
-        return "empty"
-    try:
-        with candidates.open(encoding="utf-8") as fh:
-            for raw_line in fh:
-                if raw_line.strip():
-                    return "populated"
-    except OSError:
-        return "empty"
-    return "empty"
-
-
-def _gate_for_issue(
-    repo: str,
-    issue_number: int,
-    *,
-    candidates: Path,
-    scope_rules: list[dict[str, Any]] | None,
-    source_dir: Path,
-    project_root: Path,
-) -> GateResult:
-    """Run the ``--for-issue`` sub-gates: scope + latest-decision."""
-    # Subscription: read raw.json from the cache and verify the issue is
-    # matched by the rule set. If the issue isn't cached, treat as out of
-    # scope so the operator must explicitly fetch + accept it first.
-    owner, name = repo.split("/", 1) if "/" in repo else ("", "")
-    issue_meta = source_dir / owner / name / str(issue_number) / "meta.json"
-    raw = _read_raw_issue(issue_meta) if issue_meta.is_file() else None
-    if scope_rules and raw is not None:
-        if not _issue_in_scope(scope_rules, raw, project_root=project_root):
-            msg = (
-                f"❌ deft cache-fresh: issue #{issue_number} is OUTSIDE the "
-                "active plan.policy.triageScope[] subscription.\n"
-                "  Recovery: widen the subscription (see "
-                "`deft triage:scope --list`) or open it via "
-                "`deft triage:accept -- --repo OWNER/NAME --issue "
-                f"{issue_number}` after confirming the scope rule covers it."
-            )
-            return GateResult(1, msg)
-    elif scope_rules and raw is None:
-        # We couldn't read the raw payload but rules are set; refuse so
-        # the operator must `deft cache:fetch-all` first.
-        msg = (
-            f"❌ deft cache-fresh: issue #{issue_number} is not present in "
-            f".deft-cache/{DEFAULT_SOURCE}/{repo}/ (cannot verify subscription).\n"
-            f"  Recovery: `deft cache:fetch-all -- --source {DEFAULT_SOURCE} "
-            f"--repo {repo}` and retry."
-        )
-        return GateResult(1, msg)
-
-    # Latest-decision check.
-    decision = _latest_decision_for_issue(
-        candidates, repo=repo, issue_number=issue_number
-    )
-    if decision is None:
-        msg = (
-            f"❌ deft cache-fresh: issue #{issue_number} has no triage decision "
-            f"in {candidates.relative_to(project_root)}.\n"
-            "  Recovery: `deft triage:accept -- --repo "
-            f"{repo} --issue {issue_number}` "
-            "before dispatching an implementation agent."
-        )
-        return GateResult(1, msg)
-
-    verdict = decision.get("decision", "")
-    if verdict != REQUIRED_DECISION:
-        msg = (
-            f"❌ deft cache-fresh: issue #{issue_number} latest decision "
-            f"is {verdict!r}, not {REQUIRED_DECISION!r} -- dispatch refused.\n"
-            f"  Recovery: re-evaluate via `deft triage:status -- --repo {repo} "
-            f"--issue {issue_number}` and run `deft triage:accept` once the "
-            "item is ready, or pick a different issue."
-        )
-        return GateResult(1, msg)
-
-    return GateResult(0, f"✓ issue #{issue_number} cleared (decision=accept).")
-
-
-# ---------------------------------------------------------------------------
-# CLI
-# ---------------------------------------------------------------------------
-
-
-def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        prog="preflight_cache.py",
-        description=(
-            "Pre-`start_agent` cache-freshness gate (#1127). Refuses "
-            "implementation dispatch when the triage cache is stale, "
-            "missing, or the target issue's latest decision is not "
-            "`accept`. Subscription-aware via plan.policy.triageScope[] "
-            "(D12 / #1131)."
-        ),
-    )
-    parser.add_argument(
-        "--project-root",
-        default=".",
-        help="Project root path (default: current working directory).",
-    )
-    parser.add_argument(
-        "--source",
-        default=DEFAULT_SOURCE,
-        help=(
-            "Cache source to inspect. v1 ships github-issue only "
-            "(default: github-issue)."
-        ),
-    )
-    parser.add_argument(
-        "--repo",
-        default=None,
-        help=(
-            "Upstream repo slug 'owner/name'. Resolution precedence: "
-            "(1) --repo, (2) $DEFT_TRIAGE_REPO, (3) `git remote get-url "
-            "origin`, (4) single-repo auto-detect under .deft-cache/."
-        ),
-    )
-    parser.add_argument(
-        "--max-age-hours",
-        type=int,
-        default=None,
-        help=(
-            "Override the freshness window in hours. Falls back to "
-            "$DEFT_CACHE_MAX_AGE_HOURS, then the built-in default (24h)."
-        ),
-    )
-    parser.add_argument(
-        "--for-issue",
-        type=int,
-        default=None,
-        help=(
-            "Verify a specific issue's latest decision is `accept` AND "
-            "that it is covered by plan.policy.triageScope[] (D12). "
-            "Refuses dispatch on any other decision or out-of-scope match."
-        ),
-    )
-    parser.add_argument(
-        "--allow-stale",
-        action="store_true",
-        help=(
-            "Audit-trail escape hatch: exits 0 with a stderr warning even "
-            "when the cache is stale. Per-shell only; never persisted."
-        ),
-    )
-    parser.add_argument(
-        "--allow-missing-bootstrap",
-        action="store_true",
-        help=(
-            "Bootstrap fallback (mirrors preflight_branch.py's "
-            "--allow-missing-project-definition): treat a missing "
-            ".deft-cache/ or candidates.jsonl as exit 0 instead of exit 2. "
-            "Used by the framework's own `task check` so a fresh checkout "
-            "is not gated by its own verify:cache-fresh verb. Ignored when "
-            "--for-issue is passed."
-        ),
-    )
-    parser.add_argument(
-        "--quiet",
-        action="store_true",
-        help="Suppress the OK message (errors still print to stderr).",
-    )
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = _build_parser()
-    args = parser.parse_args(argv)
-    project_root = Path(args.project_root).resolve()
-    result = evaluate(
-        project_root,
-        source=args.source,
-        repo=args.repo,
-        max_age_hours=args.max_age_hours,
-        for_issue=args.for_issue,
-        allow_stale=args.allow_stale,
-        allow_missing_bootstrap=args.allow_missing_bootstrap,
-    )
-    if result.code == 0:
-        if not args.quiet:
-            # Warning lines start with ⚠ and route to stderr so a CI run
-            # that pipes stdout into a log still captures them next to
-            # any later failures.
-            if result.message.startswith("⚠"):
-                print(result.message, file=sys.stderr)
-            else:
-                print(result.message)
-    else:
-        print(result.message, file=sys.stderr)
-    return result.code
-
-
-if __name__ == "__main__":
-    sys.exit(main())