vigil-codeintel 0.1.0__py3-none-any.whl

vigil_forensic/gate_checks/forensic_cluster_runners/advanced_checks.py

@@ -0,0 +1,322 @@
+"""Advanced cluster wrappers -- clusters 32-50, 53.
+
+Covers: hardcoded paths, boundary validation, unreachable code, shadowed
+builtins, mutable defaults, resource leaks, docstring drift, broad catch,
+debug prints, commented code, missing await, unchecked response, naive
+timezone, near-duplicate code, missing null check, path concatenation,
+log without context, test secrets, unpinned dependencies,
+legacy compatibility debt (C53).
+"""
+from __future__ import annotations
+
+from ...source_analysis import is_source_file
+from ...gate_models import GateFinding
+from ..forensic_clusters import (
+    assess_boundary_validation,
+    assess_broad_catch_no_reraise,
+    assess_commented_code,
+    assess_debug_prints,
+    assess_docstring_params,
+    assess_hardcoded_paths,
+    assess_log_without_context,
+    assess_missing_await,
+    assess_missing_null_check,
+    assess_mutable_defaults,
+    assess_naive_timezone,
+    assess_near_duplicate_code,
+    assess_path_concatenation,
+    assess_resource_leaks,
+    assess_shadowed_builtins,
+    assess_test_secrets,
+    assess_unchecked_response,
+    assess_unpinned_dependencies,
+    assess_unreachable_code,
+)
+from ._helpers import _MAX_FINDINGS_PER_CLUSTER
+import logging
+_log = logging.getLogger(__name__)
+
+
+def _check_hardcoded_paths(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_hardcoded_paths(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_boundary_validation(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not is_source_file(path) or not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_boundary_validation(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_unreachable_code(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_unreachable_code(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_shadowed_builtins(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_shadowed_builtins(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_mutable_defaults(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_mutable_defaults(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_resource_leaks(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_resource_leaks(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_docstring_params(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_docstring_params(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_broad_catch_no_reraise(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not is_source_file(path) or not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_broad_catch_no_reraise(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_debug_prints(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_debug_prints(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_commented_code(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_commented_code(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_missing_await(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_missing_await(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_unchecked_response(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_unchecked_response(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_naive_timezone(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_naive_timezone(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_near_duplicate_code(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_near_duplicate_code(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_missing_null_check(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_missing_null_check(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_path_concatenation(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_path_concatenation(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_log_without_context(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_log_without_context(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_test_secrets(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_test_secrets(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+def _check_unpinned_dependencies(ctx) -> list[GateFinding]:
+    snapshots = ctx.file_snapshots or {}
+    findings: list[GateFinding] = []
+    for path, snap in snapshots.items():
+        if not hasattr(snap, "text") or not snap.text:
+            continue
+        findings.extend(assess_unpinned_dependencies(path, snap.text))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# Cluster 53: Legacy Compatibility Debt
+# ---------------------------------------------------------------------------
+
+
+def _check_legacy_compat_debt(ctx) -> list[GateFinding]:
+    """C53: Detect forwarding wrappers, unused shims, stale markers, dead adapters."""
+    snapshots = ctx.file_snapshots or {}
+    if not snapshots:
+        return []
+    from ...gate_checks.forensic_clusters.legacy_debt import (
+        check_forwarding_wrapper,
+        check_unused_shim_module,
+        check_stale_migration_marker,
+        check_shape_adapter_without_producer,
+        build_import_index,
+    )
+    all_content = {
+        path: snap.text
+        for path, snap in snapshots.items()
+        if hasattr(snap, "text") and snap.text
+    }
+    # Build the stem -> importers index ONCE in a single O(N) pass. unused_shim
+    # then does an O(1) lookup per module instead of rescanning the whole
+    # corpus (which made the gate O(N^2) and hung on large monorepos).
+    import_index = build_import_index(all_content)
+    findings: list[GateFinding] = []
+    for path, content in all_content.items():
+        findings.extend(check_forwarding_wrapper(path, content))
+        findings.extend(check_unused_shim_module(path, content, import_index))
+        findings.extend(check_stale_migration_marker(path, content))
+        # shape_adapter keeps the corpus dict: its trigger pattern is rare, so
+        # the producer scan runs for almost no files (early-returns on no match).
+        findings.extend(check_shape_adapter_without_producer(path, content, all_content))
+        if len(findings) >= _MAX_FINDINGS_PER_CLUSTER:
+            break
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# Cluster 52: Shared Logic Fragmentation
+# ---------------------------------------------------------------------------
+
+
+def _check_shared_logic_fragmentation(ctx) -> list[GateFinding]:
+    """C52: Detect duplicate module proliferation and abstraction bypass."""
+    snapshots = ctx.file_snapshots or {}
+    if not snapshots:
+        return []
+    from ...gate_checks.forensic_clusters.structural_quality import assess_shared_logic_fragmentation
+    return assess_shared_logic_fragmentation(
+        snapshots,
+        project_dir=ctx.project_dir,
+        source_package_roots=ctx.source_package_roots,
+    )

vigil_forensic/gate_checks/forensic_cluster_runners/core.py

@@ -0,0 +1,273 @@
+"""Core orchestrator: run_forensic_cluster_checks.
+
+Imports all _check_* wrappers from sibling modules and runs them via
+_safe_run(), merging results into a single GateCheckResult.
+"""
+from __future__ import annotations
+
+import concurrent.futures
+import logging
+import time
+from typing import List
+
+from ...gate_models import GateCategory, GateCheckResult, GateFinding, PostExecGateContext
+from ..common import build_check_result
+
+from ._helpers import _safe_run
+from .integrity_checks import (
+    _check_config_applied,
+    _check_config_general,
+    _check_fallback_transparency,
+    _check_proxy_as_truth,
+    _check_state_divergence,
+    _check_success_proof,
+)
+from .quality_checks import (
+    _check_dead_code,
+    _check_dependency_vulnerabilities,
+    _check_edit_consistency,
+    _check_embedded_code_syntax,
+    _check_encoding_consistency,
+    _check_error_message_quality,
+    _check_exception_swallowing,
+    _check_http_method_consistency,
+    _check_import_cycles,
+    _check_js_surface_coverage,
+    _check_log_level_quality,
+    _check_magic_numbers,
+    _check_mutation_verified,
+    _check_naming_consistency,
+    _check_response_shape_drift,
+    _check_roundtrip_consistency,
+    _check_secrets_in_code,
+    _check_security_patterns,
+    _check_shared_mutable_state,
+    _check_test_quality,
+    _check_todo_debt,
+    _check_unused_imports,
+)
+from .advanced_checks import (
+    _check_boundary_validation,
+    _check_broad_catch_no_reraise,
+    _check_commented_code,
+    _check_debug_prints,
+    _check_docstring_params,
+    _check_hardcoded_paths,
+    _check_legacy_compat_debt,
+    _check_log_without_context,
+    _check_missing_await,
+    _check_missing_null_check,
+    _check_mutable_defaults,
+    _check_naive_timezone,
+    _check_near_duplicate_code,
+    _check_path_concatenation,
+    _check_resource_leaks,
+    _check_shadowed_builtins,
+    _check_shared_logic_fragmentation,
+    _check_test_secrets,
+    _check_unchecked_response,
+    _check_unpinned_dependencies,
+    _check_unreachable_code,
+)
+_log = logging.getLogger(__name__)
+
+_FORENSIC_CLUSTERS_TIMEOUT = 90
+
+# Cluster runners that depend on RUNTIME / verification context (artifact_refs,
+# transport_mode, reported-vs-observed changes, validation-contract proofs, or a
+# disk re-read compared against an expected hash). They are meaningful ONLY when
+# the gate runs against a real post-execution context. In *static mode* — where
+# the context is synthesised from on-disk file_snapshots alone (no artifact_refs,
+# empty transport_mode, session_number == 0) — they either trivially self-skip OR
+# emit false positives, so they are filtered out entirely.
+#
+# The worst offender is cluster11_mutation_verified: the runner hashes the
+# *decoded* snapshot text (LF, BOM-stripped) while the assessor hashes the *raw*
+# disk bytes (CRLF / BOM on Windows). On any CRLF or BOM file those hashes differ
+# → a bogus "File content DIVERGED from expected" HIGH on otherwise-clean code.
+# That check exists to catch "edit applied in memory but not on disk" and has no
+# meaning when the snapshot WAS read from disk, as it is in static mode.
+_RUNTIME_ONLY_CLUSTERS: frozenset[str] = frozenset({
+    "cluster2_success_without_proof",          # needs session_number + artifact_refs
+    "cluster4_config_accepted_ignored_proofs",  # needs validation_contract proofs + artifact_refs
+    "cluster6_state_divergence",               # reported vs observed changed files
+    "cluster7_fallback_hides_truth",           # transport_mode + artifact_refs
+    "cluster3_proxy_as_truth",                 # transport_mode + artifact_refs
+    "cluster4_config_accepted_ignored_general",  # transport_mode / project_mode / task_intent
+    "cluster10_edit_consistency",              # operator_api runtime-edit consistency
+    "cluster11_mutation_verified",             # disk re-read vs expected hash → CRLF/BOM FP
+})
+
+
+def _is_static_mode(ctx: PostExecGateContext) -> bool:
+    """True when *ctx* carries no runtime/verification context.
+
+    Static mode is how ``run_forensic_audit`` invokes the pack: the context is
+    built from on-disk ``file_snapshots`` only (see
+    ``self_audit.build_synthetic_context``) with no ``artifact_refs``, empty
+    ``transport_mode`` and ``session_number == 0``. When a real post-execution
+    context is present (any of those populated) the full pack runs unchanged.
+    """
+    has_artifacts = bool(getattr(ctx, "artifact_refs", None))
+    has_transport = bool(getattr(ctx, "transport_mode", "") or "")
+    has_session = bool(getattr(ctx, "session_number", 0))
+    return not (has_artifacts or has_transport or has_session)
+
+
+def run_forensic_cluster_checks(ctx: PostExecGateContext) -> GateCheckResult:
+    """Run universal forensic cluster checks against the real gate context.
+
+    Universal (project-agnostic) integrity clusters:
+    - C2: Success Without Proof (artifact_refs check)
+    - C3: Proxy as Truth (remote truth labeling)
+    - C4: Config Accepted Ignored (proofs + transport + classification)
+    - C6: State Divergence (reported vs observed files)
+    - C7: Fallback Hides Truth (remote mode without proof)
+
+    (C1 declared/C5 rendered/C8 dead-surface/C9 phantom were Vigil-specific and
+    removed -- they depended on INTERFACE.operator / INTERFACE.UI modules.)
+    """
+    all_findings: List[GateFinding] = []
+    error_notes: List[str] = []
+
+    def _run_all_checks() -> tuple[List[GateFinding], List[str]]:
+        _results: List[GateFinding] = []
+        _notes: List[str] = []
+        _start = time.monotonic()
+
+        _checks = [
+            # Phase 1 runners (existing)
+            ("cluster2_success_without_proof", lambda: _check_success_proof(ctx)),
+            ("cluster4_config_accepted_ignored_proofs", lambda: _check_config_applied(ctx)),
+            ("cluster6_state_divergence", lambda: _check_state_divergence(ctx)),
+            ("cluster7_fallback_hides_truth", lambda: _check_fallback_transparency(ctx)),
+            # clusters 1/5/8/9 (declared_capability, rendered_vs_live, dead_surface,
+            # phantom_capability) were REMOVED: they hardcoded Vigil's INTERFACE.operator
+            # / INTERFACE.UI modules and only ever produced false findings (ImportError /
+            # empty) on any non-Vigil project. Gone for a clean standalone package.
+            # Phase 3 runners (new)
+            ("cluster3_proxy_as_truth", lambda: _check_proxy_as_truth(ctx)),
+            ("cluster4_config_accepted_ignored_general", lambda: _check_config_general(ctx)),
+            # Phase 4 runners
+            ("cluster10_edit_consistency", lambda: _check_edit_consistency(ctx)),
+            ("cluster11_mutation_verified", lambda: _check_mutation_verified(ctx)),
+            # Phase 5 runners (universal clusters)
+            ("cluster12_security", lambda: _check_security_patterns(ctx)),
+            ("cluster13_test_quality", lambda: _check_test_quality(ctx)),
+            ("cluster14_import_cycles", lambda: _check_import_cycles(ctx)),
+            ("cluster15_roundtrip", lambda: _check_roundtrip_consistency(ctx)),
+            ("cluster16_mutable_state", lambda: _check_shared_mutable_state(ctx)),
+            # Phase 6 runners (security + code quality)
+            ("cluster17_dependency_cves", lambda: _check_dependency_vulnerabilities(ctx)),
+            ("cluster20_dead_code", lambda: _check_dead_code(ctx)),
+            ("cluster23_unused_imports", lambda: _check_unused_imports(ctx)),
+            ("cluster25_secrets", lambda: _check_secrets_in_code(ctx)),
+            # Phase 7 runners (code style + encoding)
+            ("cluster21_magic_numbers", lambda: _check_magic_numbers(ctx)),
+            ("cluster22_error_messages", lambda: _check_error_message_quality(ctx)),
+            ("cluster24_naming", lambda: _check_naming_consistency(ctx)),
+            ("cluster26_todo_debt", lambda: _check_todo_debt(ctx)),
+            ("cluster28_log_levels", lambda: _check_log_level_quality(ctx)),
+            ("cluster29_encoding", lambda: _check_encoding_consistency(ctx)),
+            # Phase 8 runners (JS/API contract drift)
+            ("cluster27_embedded_syntax", lambda: _check_embedded_code_syntax(ctx)),
+            ("cluster28b_response_shape", lambda: _check_response_shape_drift(ctx)),
+            ("cluster29b_method_consistency", lambda: _check_http_method_consistency(ctx)),
+            ("cluster30_js_coverage", lambda: _check_js_surface_coverage(ctx)),
+            # Phase 9 runners (fail-loud, portability, security boundaries)
+            ("cluster31_exception_swallowing", lambda: _check_exception_swallowing(ctx)),
+            ("cluster32_hardcoded_paths", lambda: _check_hardcoded_paths(ctx)),
+            ("cluster33_boundary_validation", lambda: _check_boundary_validation(ctx)),
+            # Phase 10 runners (deep code quality + language-agnostic)
+            ("cluster34_unreachable_code", lambda: _check_unreachable_code(ctx)),
+            ("cluster35_shadowed_builtins", lambda: _check_shadowed_builtins(ctx)),
+            ("cluster36_mutable_defaults", lambda: _check_mutable_defaults(ctx)),
+            ("cluster37_resource_leaks", lambda: _check_resource_leaks(ctx)),
+            ("cluster38_docstring_drift", lambda: _check_docstring_params(ctx)),
+            ("cluster39_broad_catch", lambda: _check_broad_catch_no_reraise(ctx)),
+            ("cluster40_debug_prints", lambda: _check_debug_prints(ctx)),
+            ("cluster41_commented_code", lambda: _check_commented_code(ctx)),
+            # Phase 11 runners (async, API safety, dependencies)
+            ("cluster42_missing_await", lambda: _check_missing_await(ctx)),
+            ("cluster43_unchecked_response", lambda: _check_unchecked_response(ctx)),
+            ("cluster44_naive_timezone", lambda: _check_naive_timezone(ctx)),
+            ("cluster45_near_duplicate", lambda: _check_near_duplicate_code(ctx)),
+            ("cluster46_null_check", lambda: _check_missing_null_check(ctx)),
+            ("cluster47_path_concat", lambda: _check_path_concatenation(ctx)),
+            ("cluster48_log_context", lambda: _check_log_without_context(ctx)),
+            ("cluster49_test_secrets", lambda: _check_test_secrets(ctx)),
+            ("cluster50_unpinned_deps", lambda: _check_unpinned_dependencies(ctx)),
+            # Phase 12 runners (C52: structural quality)
+            ("cluster52_shared_logic_fragmentation", lambda: _check_shared_logic_fragmentation(ctx)),
+            # Phase 13 runners (C53: legacy compatibility debt)
+            ("cluster53_legacy_compat_debt", lambda: _check_legacy_compat_debt(ctx)),
+        ]
+
+        # In static mode (no runtime/verification context) drop the runtime-only
+        # clusters so the static-safe subset (security, secrets, mutable defaults,
+        # resource leaks, dead code, …) still runs without emitting runtime FPs.
+        if _is_static_mode(ctx):
+            _dropped = [lbl for lbl, _ in _checks if lbl in _RUNTIME_ONLY_CLUSTERS]
+            _checks = [(lbl, fn) for lbl, fn in _checks if lbl not in _RUNTIME_ONLY_CLUSTERS]
+            if _dropped:
+                _log.debug(
+                    "forensic_clusters: static mode — skipped %d runtime-only "
+                    "cluster(s): %s", len(_dropped), ", ".join(_dropped),
+                )
+
+        from vigil_forensic.self_audit import get_cancel_event
+        for label, fn in _checks:
+            _cancel = get_cancel_event()
+            if _cancel is not None and _cancel.is_set():
+                _log.info("forensic_clusters: cancel_event set, stopping at %s", label)
+                break
+            _elapsed = time.monotonic() - _start
+            if _elapsed > _FORENSIC_CLUSTERS_TIMEOUT - 10:  # 10s safety margin
+                _log.warning(
+                    "post_exec_gate: forensic_clusters timeout threshold approaching "
+                    "(%.1fs / %ds), stopping early",
+                    _elapsed, _FORENSIC_CLUSTERS_TIMEOUT,
+                )
+                break
+            _safe_run(label, fn, _results, _notes)
+
+        return _results, _notes
+
+    executor = concurrent.futures.ThreadPoolExecutor(max_workers=1)
+    try:
+        all_findings, error_notes = executor.submit(_run_all_checks).result(
+            timeout=_FORENSIC_CLUSTERS_TIMEOUT
+        )
+    except concurrent.futures.TimeoutError:
+        _log.error(
+            "post_exec_gate: forensic_clusters total execution timeout (%ds reached)",
+            _FORENSIC_CLUSTERS_TIMEOUT,
+        )
+        all_findings = []
+        error_notes = []
+    finally:
+        executor.shutdown(wait=False)
+
+    # Apply false positive allowlist with revalidation
+    from ..forensic_clusters import load_allowlist, filter_by_allowlist
+    try:
+        allowlist = load_allowlist(ctx.project_dir)
+        if allowlist:
+            all_findings, filtered, revalidation_notes = filter_by_allowlist(
+                all_findings, allowlist, project_dir=ctx.project_dir,
+            )
+            error_notes.extend(revalidation_notes)
+            if filtered:
+                error_notes.append(
+                    f"[allowlist] Filtered {len(filtered)} finding(s) via false_positive_allowlist.json "
+                    f"({sum(1 for e in allowlist if e.is_valid())} valid entries)"
+                )
+    except (OSError, KeyError, ValueError, TypeError):
+        pass  # allowlist failure must not block forensics
+
+    return build_check_result(
+        check_id="forensic_clusters",
+        category=GateCategory.CONTRACT,
+        findings=all_findings,
+        notes=error_notes,
+    )