vigil-codeintel 0.1.0__py3-none-any.whl

vigil_forensic/gate_checks/size_complexity_checks.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+import logging
+
+from vigil_forensic._shared import EvidenceReference, GateCategory, GateImpact, GateSeverity, RepairKind
+from vigil_forensic.gate_models import PostExecGateContext
+from ..source_analysis import extract_functions, get_language_id, is_source_file
+from .common import build_check_result, build_finding, is_generated_file, iter_touched_snapshots, max_nesting_depth, normalize_path
+
+_log = logging.getLogger(__name__)
+
+
+def _suppress_for_data_module(
+    snapshot,
+    file_warn: int,
+    file_revise: int,
+    fn_warn: int,
+    fn_revise: int,
+    nest_warn: int,
+    nest_revise: int,
+) -> bool:
+    """Return True iff legacy thresholds would emit ANY size_complexity finding.
+
+    Used by the Sprint B4 data_module branch to decide whether a single
+    ``applicability=not_applicable`` summary finding should be surfaced.
+    If legacy thresholds would not flag the file anyway, skip silently
+    (no NA finding inflation).
+    """
+    if snapshot.line_count >= file_warn:
+        return True
+    if is_source_file(snapshot.path):
+        try:
+            for fi in extract_functions(snapshot.path, snapshot.text):
+                if fi.line_count >= fn_warn:
+                    return True
+        except Exception:  # pragma: no cover -- fail-open
+            return False
+        if get_language_id(snapshot.path) == "python":
+            if max_nesting_depth(snapshot.text) >= nest_warn:
+                return True
+    return False
+
+# NOTE: the size_complexity.zone_overload sub-check was REMOVED (FP fix).
+# It inferred "responsibility zones" from function-name prefixes — the exact
+# same name-prefix heuristic as god_object_zones — and double-reported every
+# file that god_object_zones already flagged (e.g. 7 + 5 findings on the same
+# filelock files). The zone heuristic now has a single home in the opt-in
+# god_object_zones gate (see self_audit._NOISY_OPT_IN_GATES). size_complexity
+# keeps only its objective size / function-length / nesting budget checks.
+
+
+def run_size_complexity_checks(ctx: PostExecGateContext):
+    findings = []
+    profile = ctx.repo_profile
+    thresholds = (profile.size_thresholds if profile is not None else {}) or {}
+    file_warn = int(thresholds.get("file_warn", 600))
+    file_revise = int(thresholds.get("file_revise", 800))
+    fn_warn = int(thresholds.get("function_warn", 80))
+    fn_revise = int(thresholds.get("function_revise", 120))
+    nest_warn = int(thresholds.get("nesting_warn", 4))
+    nest_revise = int(thresholds.get("nesting_revise", 6))
+    # Sprint B4: optional per-file role map (ProjectContext.file_roles).
+    # None when ctx.project_context is absent (legacy path) or when the
+    # light-tier build is in use. Gate behavior degrades gracefully: when
+    # file_roles is None or role.kind is in {"code_module", "generated",
+    # "unknown", "test_module"}, legacy threshold + F16d marker + allowlist
+    # logic applies unchanged. Only role.kind == "data_module" takes the
+    # new suppression branch.
+    file_roles = getattr(getattr(ctx, "project_context", None), "file_roles", None)
+
+    # Sprint C2 (2026-04-23): prefer TestTopology.is_test_path for test-path
+    # skip. Legacy basename check preserved as fallback.
+    topology = getattr(getattr(ctx, "project_context", None), "test_topology", None)
+
+    for snapshot in iter_touched_snapshots(ctx):
+        if not snapshot.exists:
+            continue
+        norm_path = snapshot.path.replace("\\", "/")
+        if topology is not None:
+            if topology.is_test_path(norm_path):
+                continue
+        elif norm_path.split("/")[-1].startswith("test_"):
+            continue
+        if profile and snapshot.path in profile.allowlisted_large_files:
+            continue
+        # F16d: skip auto-generated files and sanctioned asset bundles.
+        if is_generated_file(snapshot.text):
+            _log.debug(
+                "size_complexity: skipping generated/sanctioned file %s",
+                snapshot.path,
+            )
+            continue
+
+        # Sprint B4: density-based suppression for data-dominant modules.
+        # Catalog/registry files (e.g. GATE_SPECS = (...)) are measured by
+        # thresholds designed for code; surface a single not_applicable
+        # finding when legacy thresholds would have flagged, then skip the
+        # rest of the per-file checks.
+        if file_roles is not None:
+            role = file_roles.role(snapshot.path)
+            if role.kind == "data_module":
+                if _suppress_for_data_module(
+                    snapshot,
+                    file_warn,
+                    file_revise,
+                    fn_warn,
+                    fn_revise,
+                    nest_warn,
+                    nest_revise,
+                ):
+                    pct = int(round(role.metrics.data_density_ratio * 100))
+                    findings.append(
+                        build_finding(
+                            check_id="size.applicability_suppressed",
+                            category=GateCategory.SIZE_COMPLEXITY,
+                            title="Size/complexity thresholds not applicable to data module",
+                            severity=GateSeverity.LOW,
+                            impact=GateImpact.WARN,
+                            summary=(
+                                f"{snapshot.path} is a data-dominant module "
+                                f"({pct}% literal content); size thresholds "
+                                f"designed for code modules do not apply."
+                            ),
+                            recommendation=(
+                                "Treat catalog/registry files as data, not "
+                                "code: exempt from LOC/function/nesting "
+                                "budgets."
+                            ),
+                            evidence=[EvidenceReference(kind="file", path=snapshot.path)],
+                            repair_kind="",
+                            executor_action="",
+                            proof_required="",
+                            allowlist_allowed=True,
+                            applicability="not_applicable",
+                            applicability_reason=role.reason,
+                            analysis_mode="role_map",
+                            confidence=0.9,
+                        )
+                    )
+                _log.debug(
+                    "size_complexity: skipping data_module %s (data_density=%.2f code_density=%.2f)",
+                    snapshot.path,
+                    role.metrics.data_density_ratio,
+                    role.metrics.code_density_ratio,
+                )
+                continue
+            # Other role kinds fall through to legacy path.
+        if snapshot.line_count >= file_revise:
+            findings.append(
+                build_finding(
+                    check_id="size.file_too_large",
+                    category=GateCategory.SIZE_COMPLEXITY,
+                    title="Touched file exceeds the revise threshold",
+                    severity=GateSeverity.HIGH,
+                    impact=GateImpact.REVISE,
+                    summary=f"{snapshot.path} is {snapshot.line_count} lines; profile revise threshold is {file_revise}.",
+                    recommendation="Split responsibilities or move new logic into smaller modules.",
+                    evidence=[EvidenceReference(kind="file", path=snapshot.path)],
+                    repair_kind=RepairKind.SPLIT_MODULE.value,
+                    executor_action=f"Split {snapshot.path} — {snapshot.line_count} lines exceeds {file_revise}-line threshold; extract each responsibility into a focused module",
+                    proof_required="file below threshold after split; grep confirms no logic removed",
+                    allowlist_allowed=False,
+                )
+            )
+        elif snapshot.line_count >= file_warn:
+            findings.append(
+                build_finding(
+                    check_id="size.file_warn",
+                    category=GateCategory.SIZE_COMPLEXITY,
+                    title="Touched file exceeds the warning threshold",
+                    severity=GateSeverity.MEDIUM,
+                    impact=GateImpact.REVISE,
+                    summary=f"{snapshot.path} is {snapshot.line_count} lines; profile warning threshold is {file_warn}.",
+                    recommendation="Keep the file from becoming a new god-file.",
+                    evidence=[EvidenceReference(kind="file", path=snapshot.path)],
+                    repair_kind=RepairKind.SPLIT_MODULE.value,
+                    executor_action=f"Watch {snapshot.path} — {snapshot.line_count} lines approaching {file_revise}-line revise threshold",
+                )
+            )
+        if is_source_file(snapshot.path):
+            for fi in extract_functions(snapshot.path, snapshot.text):
+                if fi.line_count >= fn_revise:
+                    findings.append(
+                        build_finding(
+                            check_id="size.function_too_large",
+                            category=GateCategory.SIZE_COMPLEXITY,
+                            title="Touched function exceeds the revise threshold",
+                            severity=GateSeverity.HIGH,
+                            impact=GateImpact.REVISE,
+                            summary=f"{snapshot.path}::{fi.name} is {fi.line_count} lines; profile revise threshold is {fn_revise}.",
+                            recommendation="Split orchestration, logic, and rendering into smaller helpers.",
+                            evidence=[EvidenceReference(kind="file", path=snapshot.path, detail=fi.name)],
+                            repair_kind=RepairKind.REFACTOR.value,
+                            executor_action=f"Refactor {snapshot.path}::{fi.name} — {fi.line_count} lines; extract sub-steps into named helpers",
+                            proof_required="function below threshold; tests still pass",
+                            allowlist_allowed=False,
+                        )
+                    )
+                    break
+                if fi.line_count >= fn_warn:
+                    findings.append(
+                        build_finding(
+                            check_id="size.function_warn",
+                            category=GateCategory.SIZE_COMPLEXITY,
+                            title="Touched function exceeds the warning threshold",
+                            severity=GateSeverity.MEDIUM,
+                            impact=GateImpact.REVISE,
+                            summary=f"{snapshot.path}::{fi.name} is {fi.line_count} lines; profile warning threshold is {fn_warn}.",
+                            recommendation="Watch for mixed responsibility growth.",
+                            evidence=[EvidenceReference(kind="file", path=snapshot.path, detail=fi.name)],
+                            repair_kind=RepairKind.REFACTOR.value,
+                            executor_action=f"Watch {snapshot.path}::{fi.name} — {fi.line_count} lines approaching revise threshold",
+                        )
+                    )
+                    break
+            if get_language_id(snapshot.path) == "python":
+                nesting = max_nesting_depth(snapshot.text)
+                if nesting >= nest_revise:
+                    findings.append(
+                        build_finding(
+                            check_id="size.nesting_too_high",
+                            category=GateCategory.SIZE_COMPLEXITY,
+                            title="Touched code exceeds nesting threshold",
+                            severity=GateSeverity.HIGH,
+                            impact=GateImpact.REVISE,
+                            summary=f"{snapshot.path} reaches nesting depth {nesting}; profile revise threshold is {nest_revise}.",
+                            recommendation="Flatten control flow or extract helpers.",
+                            evidence=[EvidenceReference(kind="file", path=snapshot.path)],
+                            repair_kind=RepairKind.REFACTOR.value,
+                            executor_action=f"Flatten {snapshot.path} — nesting depth {nesting} exceeds {nest_revise}; use early returns",
+                            proof_required="nesting depth below threshold; tests still pass",
+                            allowlist_allowed=False,
+                        )
+                    )
+                elif nesting >= nest_warn:
+                    findings.append(
+                        build_finding(
+                            check_id="size.nesting_warn",
+                            category=GateCategory.SIZE_COMPLEXITY,
+                            title="Touched code exceeds warning nesting threshold",
+                            severity=GateSeverity.MEDIUM,
+                            impact=GateImpact.REVISE,
+                            summary=f"{snapshot.path} reaches nesting depth {nesting}; profile warning threshold is {nest_warn}.",
+                            recommendation="Prefer early exits and smaller helpers.",
+                            evidence=[EvidenceReference(kind="file", path=snapshot.path)],
+                            repair_kind=RepairKind.REFACTOR.value,
+                            executor_action=f"Watch {snapshot.path} — nesting depth {nesting} approaching {nest_revise} revise threshold",
+                        )
+                    )
+        # size_complexity.zone_overload removed (FP fix): name-prefix zone
+        # inference now lives only in the opt-in god_object_zones gate.
+    return build_check_result(check_id="size_complexity", category=GateCategory.SIZE_COMPLEXITY, findings=findings)
+
+
+# ---------------------------------------------------------------------------
+# hotspot_inflation gate
+# ---------------------------------------------------------------------------
+
+_MODE_DO_NOT_TOUCH = "do_not_touch_without_runtime_trace"
+_MODE_FORENSIC_FIRST = "forensic_first"
+
+
+def run_hotspot_inflation_checks(ctx: PostExecGateContext):
+    """Emit a finding for every touched file that is a high-risk hotspot in ctx.maps.
+
+    Modes that trigger findings:
+      - do_not_touch_without_runtime_trace -> HIGH severity
+      - forensic_first                     -> MEDIUM severity
+
+    No file-fallback: hotspot data is only available via ctx.maps.
+    When ctx.maps is absent or missing, return empty findings (fail-open).
+    """
+    if ctx.maps is None or getattr(ctx.maps, "missing", False):
+        _log.debug("hotspot_inflation: ctx.maps not available -- skipping")
+        return build_check_result(
+            check_id="hotspot_inflation",
+            category=GateCategory.SIZE_COMPLEXITY,
+            notes=("maps not available -- skipping",),
+        )
+
+    hotspots = getattr(ctx.maps, "hotspot", ()) or ()
+    hotspot_by_target: dict[str, object] = {
+        normalize_path(h.target): h for h in hotspots
+    }
+
+    findings = []
+    for raw_path in (ctx.touched_files or ()):
+        normalized = normalize_path(raw_path)
+        h = hotspot_by_target.get(normalized)
+        if h is None:
+            continue
+        mode = (getattr(h, "recommended_mode", "") or "").lower()
+        if mode == _MODE_DO_NOT_TOUCH:
+            severity = GateSeverity.HIGH
+            impact = GateImpact.REVISE
+            recommendation = (
+                "Capture startup trace + regression tests before merging. "
+                "This file must not be modified without a runtime trace per map_builder policy."
+            )
+        elif mode == _MODE_FORENSIC_FIRST:
+            severity = GateSeverity.MEDIUM
+            impact = GateImpact.REVISE
+            recommendation = (
+                "Run forensic gates + authority check before refactoring. "
+                "This file is flagged forensic_first in the hotspot map."
+            )
+        else:
+            _log.debug("hotspot_inflation: %s mode=%r -- not actionable, skipping", normalized, mode)
+            continue
+
+        hotspot_score = getattr(h, "hotspot_score", 0)
+        findings.append(
+            build_finding(
+                check_id="hotspot_inflation",
+                category=GateCategory.SIZE_COMPLEXITY,
+                title=f"Touched high-risk hotspot ({mode})",
+                severity=severity,
+                impact=impact,
+                summary=(
+                    f"{normalized}: hotspot_score={hotspot_score}, mode={mode}. "
+                    f"Modifying this file requires pre-change forensic trace per map_builder policy."
+                ),
+                recommendation=recommendation,
+                evidence=(EvidenceReference(kind="file", path=normalized),),
+                repair_kind=RepairKind.REFACTOR.value,
+                executor_action="Address finding details",
+                proof_required="Performance acceptable",
+                allowlist_allowed=False,
+            )
+        )
+
+    return build_check_result(
+        check_id="hotspot_inflation",
+        category=GateCategory.SIZE_COMPLEXITY,
+        findings=findings,
+    )

vigil_forensic/gate_checks/stuck_feature_flag_checks.py

@@ -0,0 +1,354 @@
+"""Stuck feature flag forensic gate.
+
+Detects module-level UPPER_SNAKE_CASE constants assigned to ``False`` that:
+    1. are referenced inside an ``if`` test somewhere in the touched files,
+    2. are never reassigned to a non-False value anywhere in the touched files,
+    3. are not part of a re-export chain (only False-default literals count).
+
+The result is a "stuck flag": code is permanently gated off and forgotten.
+Real-world example from this codebase: ``plan_review_ran = False`` hardcoded
+with the actual review code never running.
+
+Project-agnostic — works for any Python codebase. Operates strictly on
+``ctx.touched_files`` (only ``.py``); files outside ``ctx.project_dir`` are
+skipped.
+
+Algorithm:
+    Pass 1: collect module-level ``Assign(target=Name(UPPER), value=Constant(False))``
+            (excluding TypeVar-style and dunder names).
+    Pass 2: across ALL touched .py files, locate any other assignment to the
+            same name whose RHS is NOT ``Constant(False)`` — anything else
+            (True, function call, attribute, name reference) marks the name as
+            "dynamic" and disqualifies it.
+    Pass 3: across ALL touched .py files, scan ``If.test`` for usage of the
+            candidate name (as bare ``Name``, ``not NAME``, inside ``BoolOp``,
+            or as left side of ``Compare``).
+
+A finding is emitted for each name with at least one If usage AND no dynamic
+assignment.
+"""
+from __future__ import annotations
+
+import ast
+import logging
+import re
+from pathlib import Path
+from typing import Iterable
+
+from vigil_forensic.gate_models import PostExecGateContext
+from vigil_forensic.meta_findings import emit_meta_finding
+from vigil_forensic._shared import (
+    EvidenceReference,
+    GateCategory,
+    GateCheckResult,
+    GateImpact,
+    GateSeverity,
+    RepairKind,
+)
+
+from .common import build_check_result, build_finding, normalize_path
+
+_log = logging.getLogger(__name__)
+
+_CATEGORY = GateCategory.DRIFT
+_CHECK_ID = "stuck_feature_flag"
+
+# UPPER_SNAKE_CASE: leading underscore allowed (private module constants).
+# At least one alpha char and one underscore-or-alphanum to avoid lone-letter
+# matches like ``X = False`` (which is almost never a feature flag).
+_UPPER_SNAKE_RE = re.compile(r"^_?[A-Z][A-Z0-9_]*[A-Z0-9]$")
+
+
+def _is_false_constant(node: ast.AST) -> bool:
+    return (
+        isinstance(node, ast.Constant)
+        and isinstance(node.value, bool)
+        and node.value is False
+    )
+
+
+def _module_level_false_assign_target(node: ast.AST) -> str | None:
+    """Return the constant name iff *node* is ``NAME = False`` at module top.
+
+    Caller is responsible for ensuring *node* is a direct child of the module
+    (not inside a function/class body).
+    """
+    if not isinstance(node, ast.Assign):
+        return None
+    if len(node.targets) != 1:
+        return None
+    target = node.targets[0]
+    if not isinstance(target, ast.Name):
+        return None
+    name = target.id
+    if not _UPPER_SNAKE_RE.match(name):
+        return None
+    if name.startswith("__") and name.endswith("__"):
+        return None
+    if not _is_false_constant(node.value):
+        return None
+    return name
+
+
+def _module_level_assign_targets(node: ast.AST) -> list[tuple[str, ast.AST]]:
+    """Return (name, value) pairs for any module-level ``NAME = <expr>``
+    assignment whose target is a single Name. Used by the dynamic-assignment
+    pass to detect "assigned to non-False elsewhere".
+    """
+    out: list[tuple[str, ast.AST]] = []
+    if isinstance(node, ast.Assign):
+        if len(node.targets) == 1 and isinstance(node.targets[0], ast.Name):
+            out.append((node.targets[0].id, node.value))
+    elif isinstance(node, ast.AugAssign) and isinstance(node.target, ast.Name):
+        # ``X |= True`` etc. — counts as dynamic.
+        out.append((node.target.id, node.value))
+    elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+        if node.value is not None:
+            out.append((node.target.id, node.value))
+    return out
+
+
+def _walk_assigns_anywhere(tree: ast.AST) -> Iterable[tuple[str, ast.AST]]:
+    """Yield (name, value) for every ``Name = <expr>`` assignment found
+    anywhere in the tree (module-level OR inside functions/classes). Used
+    to detect cross-scope dynamic reassignment of a candidate flag.
+    """
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Assign):
+            for tgt in node.targets:
+                if isinstance(tgt, ast.Name):
+                    yield (tgt.id, node.value)
+                elif isinstance(tgt, (ast.Tuple, ast.List)):
+                    for elt in tgt.elts:
+                        if isinstance(elt, ast.Name):
+                            yield (elt.id, node.value)
+        elif isinstance(node, ast.AugAssign) and isinstance(node.target, ast.Name):
+            yield (node.target.id, node.value)
+        elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            if node.value is not None:
+                yield (node.target.id, node.value)
+
+
+def _name_is_used_in_if_test(test: ast.AST, name: str) -> bool:
+    """Return True if *test* references *name* in any of the supported forms.
+
+    Supported:
+      * ``Name(id=NAME)`` — bare reference
+      * ``UnaryOp(op=Not, operand=Name(id=NAME))`` — ``if not NAME``
+      * ``BoolOp(values=[..., Name(id=NAME), ...])`` — ``if NAME and X``
+      * ``Compare(left=Name(id=NAME), ...)`` — ``if NAME == X``
+    """
+    if isinstance(test, ast.Name) and test.id == name:
+        return True
+    if (
+        isinstance(test, ast.UnaryOp)
+        and isinstance(test.op, ast.Not)
+        and isinstance(test.operand, ast.Name)
+        and test.operand.id == name
+    ):
+        return True
+    if isinstance(test, ast.BoolOp):
+        for v in test.values:
+            if _name_is_used_in_if_test(v, name):
+                return True
+    if isinstance(test, ast.Compare):
+        if isinstance(test.left, ast.Name) and test.left.id == name:
+            return True
+        for cmp_node in test.comparators:
+            if isinstance(cmp_node, ast.Name) and cmp_node.id == name:
+                return True
+    return False
+
+
+def _collect_if_usage_sites(tree: ast.AST, name: str) -> list[int]:
+    """Return 1-based line numbers of every ``If`` whose test references *name*."""
+    lines: list[int] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.If) and _name_is_used_in_if_test(node.test, name):
+            line = getattr(node, "lineno", 0) or 0
+            if line:
+                lines.append(int(line))
+    return lines
+
+
+def _resolve_target_path(project_dir: Path, raw_path: str) -> Path | None:
+    """Resolve *raw_path* to an absolute Path inside *project_dir*. Return
+    ``None`` for files outside the project, missing files, or non-``.py``
+    files.
+    """
+    rel = normalize_path(raw_path)
+    if not rel.lower().endswith(".py"):
+        return None
+    candidate = (project_dir / rel).resolve()
+    try:
+        project_resolved = project_dir.resolve()
+    except OSError:
+        return None
+    try:
+        candidate.relative_to(project_resolved)
+    except ValueError:
+        return None
+    if not candidate.exists() or not candidate.is_file():
+        return None
+    return candidate
+
+
+def run_stuck_feature_flag_checks(ctx: PostExecGateContext) -> GateCheckResult:
+    """Detect stuck feature flags in ``ctx.touched_files`` (Python only).
+
+    Returns a GateCheckResult with one finding per stuck flag (advisory WARN).
+    """
+    project_dir = ctx.project_dir
+    touched = tuple(ctx.touched_files or ())
+    if not touched:
+        return build_check_result(
+            check_id=_CHECK_ID,
+            category=_CATEGORY,
+            notes=[f"{_CHECK_ID}: no touched files"],
+        )
+
+    # Maps name -> (rel_path, line). Uses first-seen False assignment;
+    # subsequent False assignments to the same name are tolerated (they are
+    # still "False" — not dynamic). The recorded site is the canonical
+    # evidence pointer in the finding.
+    false_assignments: dict[str, tuple[str, int]] = {}
+    # Maps name -> list of (rel_path, line) where it is reassigned to non-False
+    # (anywhere — module level, function body, class body). Presence
+    # disqualifies the name.
+    dynamic_assignments: dict[str, list[tuple[str, int]]] = {}
+    # Maps name -> list of (rel_path, line) for if-test usage sites.
+    if_usage_sites: dict[str, list[tuple[str, int]]] = {}
+
+    for raw_path in touched:
+        abs_path = _resolve_target_path(project_dir, raw_path)
+        if abs_path is None:
+            continue
+        rel_path = normalize_path(raw_path)
+        try:
+            source = abs_path.read_text(encoding="utf-8", errors="replace")
+        except OSError as exc:
+            emit_meta_finding(
+                "meta.file_unreadable",
+                path=rel_path,
+                detail=f"{type(exc).__name__}: {exc}",
+            )
+            continue
+        try:
+            tree = ast.parse(source, filename=str(abs_path))
+        except SyntaxError as exc:
+            emit_meta_finding(
+                "meta.syntax_parse_error",
+                path=rel_path,
+                detail=f"line {exc.lineno}: {exc.msg}",
+            )
+            continue
+
+        # Pass 1 — module-level NAME = False
+        for node in ast.iter_child_nodes(tree):
+            name = _module_level_false_assign_target(node)
+            if name is None:
+                continue
+            line = int(getattr(node, "lineno", 0) or 0)
+            false_assignments.setdefault(name, (rel_path, line))
+
+        # Pass 2 — any assignment anywhere whose RHS is NOT Constant(False)
+        for name, value in _walk_assigns_anywhere(tree):
+            if not _UPPER_SNAKE_RE.match(name):
+                continue
+            if name.startswith("__") and name.endswith("__"):
+                continue
+            if _is_false_constant(value):
+                continue
+            line = int(getattr(value, "lineno", 0) or 0)
+            dynamic_assignments.setdefault(name, []).append((rel_path, line))
+
+    # Pass 3 — if-test usage scan. Only do this for names that survived
+    # pass 1 + pass 2 (cheap optimisation; correctness is unchanged).
+    candidates = {
+        name for name in false_assignments if name not in dynamic_assignments
+    }
+    if not candidates:
+        return build_check_result(
+            check_id=_CHECK_ID,
+            category=_CATEGORY,
+            notes=[f"{_CHECK_ID}: no candidate False-default constants found"],
+        )
+
+    for raw_path in touched:
+        abs_path = _resolve_target_path(project_dir, raw_path)
+        if abs_path is None:
+            continue
+        rel_path = normalize_path(raw_path)
+        try:
+            source = abs_path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        try:
+            tree = ast.parse(source, filename=str(abs_path))
+        except SyntaxError:
+            continue
+
+        for name in candidates:
+            for line in _collect_if_usage_sites(tree, name):
+                if_usage_sites.setdefault(name, []).append((rel_path, line))
+
+    # Emit findings.
+    findings = []
+    for name in sorted(candidates):
+        usages = if_usage_sites.get(name, [])
+        if not usages:
+            continue
+        decl_path, decl_line = false_assignments[name]
+        evidence: list[EvidenceReference] = [
+            EvidenceReference(
+                kind="false_default_assignment",
+                path=decl_path,
+                detail=f"{decl_path}:{decl_line}: {name} = False",
+            )
+        ]
+        for use_path, use_line in usages:
+            evidence.append(
+                EvidenceReference(
+                    kind="if_test_usage",
+                    path=use_path,
+                    detail=f"{use_path}:{use_line}: if-test references {name}",
+                )
+            )
+        findings.append(
+            build_finding(
+                check_id=_CHECK_ID,
+                category=_CATEGORY,
+                title=f"Stuck feature flag: {name}",
+                severity=GateSeverity.MEDIUM,
+                impact=GateImpact.WARN,
+                summary=(
+                    f"Module constant {name}=False at {decl_path}:{decl_line} "
+                    f"is used in {len(usages)} conditional(s) but never "
+                    f"reassigned anywhere in the project. Likely dead/disabled "
+                    f"feature."
+                ),
+                recommendation=(
+                    "Either remove the flag and the gated code, or wire up a "
+                    "path that sets it to True."
+                ),
+                evidence=evidence,
+                repair_kind=RepairKind.REMOVE_DEAD_SURFACE.value,
+                executor_action="Resolve stuck feature flag (remove or wire)",
+                proof_required="Flag is either deleted (with its gated code) or set to True via a real code path.",
+                allowlist_allowed=True,
+                preferred_fix_shape="delete the flag + the dead branch, OR add the missing assignment path",
+            )
+        )
+
+    notes: list[str] = []
+    if not findings:
+        notes.append(
+            f"{_CHECK_ID}: {len(candidates)} False-default candidate(s) "
+            f"found, none with if-test usage"
+        )
+    return build_check_result(
+        check_id=_CHECK_ID,
+        category=_CATEGORY,
+        findings=findings,
+        notes=notes,
+    )