Signal Reference¶

Drift tracks 24 configured signals across architectural erosion, security-by-default, and AI-quality patterns. 19 signals are currently scoring-active and 5 remain report-only. The current report-only set is TVS, TSA, CXS, CIR, and DCA; FOE, MAZ, ISD, HSC, and PHR are now part of the scoring model.

Signal Table (All 24)¶

Abbrev	Signal	Mode	What it detects
PFS	Pattern Fragmentation	Scoring	Multiple incompatible implementation patterns in the same module.
AVS	Architecture Violations	Scoring	Imports crossing intended layer boundaries or structural boundaries.
MDS	Mutant Duplicates	Scoring	Near-duplicate functions/classes diverging in subtle ways.
EDS	Explainability Deficit	Scoring	Complex code lacking tests, docs, or type/context signals.
TVS	Temporal Volatility	Report-only	Files with anomalous churn and instability over git history.
SMS	System Misalignment	Scoring	Imports or patterns that are foreign to the target module context.
DIA	Doc-Implementation Drift	Scoring	Documented architecture that no longer matches actual code.
BEM	Broad Exception Monoculture	Scoring	Overuse of broad exception handling and swallowed failures.
TPD	Test Polarity Deficit	Scoring	Tests with insufficient negative/failure-path assertions.
GCD	Guard Clause Deficit	Scoring	Public functions lacking early input/precondition guards.
COD	Cohesion Deficit	Scoring	Modules/classes mixing unrelated responsibilities and dependencies.
NBV	Naming Contract Violation	Scoring	Naming patterns that diverge from dominant project conventions.
BAT	Bypass Accumulation	Scoring	Accumulation of TODO/FIXME/HACK and disabled-check bypasses.
ECM	Exception Contract Drift	Scoring	Inconsistent exception taxonomies and handling contracts.
CCC	Co-Change Coupling	Scoring	Files that repeatedly change together without explicit dependency.
TSA	TypeScript Architecture	Report-only	TS/JS architecture violations (layer leaks, cycles, cross-package imports, UI-to-infra imports).
CXS	Cognitive Complexity	Report-only	Functions with deeply nested, hard-to-follow control flow.
FOE	Fan-Out Explosion	Scoring	Modules/functions with unusually high dependency fan-out.
CIR	Circular Import	Report-only	Circular dependency chains in the module import graph.
DCA	Dead Code Accumulation	Report-only	Unreferenced functions/classes/symbols accumulating over time.
MAZ	Missing Authorization	Scoring	API endpoints lacking auth/authz checks (CWE-862).
ISD	Insecure Default	Scoring	Unsafe default config patterns (CWE-1188).
HSC	Hardcoded Secret	Scoring	Embedded secrets/tokens/credentials in source (CWE-798).
PHR	Phantom Reference	Scoring	Unresolvable function/class references — AI hallucination indicator.

Signal-derived negative context¶

Some signals additionally emit agent-facing anti-pattern warnings via negative_context (JSON output and agent task output).

Contributor rule:

When introducing or promoting a signal, explicitly decide whether it should produce negative context. If it should, update both in src/drift/negative_context.py:

_SIGNAL_CATEGORY mapping
@_register(SignalType.XXX) generator

Reference: Negative Context

Core Signals¶

Pattern Fragmentation (PFS)¶

What it detects: Same category of pattern implemented N different ways within one module.

Example: Error handling split across try/except, bare except, logging-only, and re-raise patterns in the same API module.

Score: 1 - (1 / num_variants) — 4 variants → 0.75 (HIGH)

Architecture Violations (AVS)¶

What it detects: Imports that cross layer boundaries or create circular dependencies.

Example: A database model importing from an API route handler.

Techniques: Import graph analysis, layer inference, hub dampening, Tarjan SCC.

Mutant Duplicates (MDS)¶

What it detects: Near-identical functions that diverge in subtle ways.

Example: validate_user() and validate_admin() sharing 90% identical AST structure.

Techniques: AST n-gram Jaccard similarity, LOC bucketing, optional FAISS embeddings.

Explainability Deficit (EDS)¶

What it detects: Complex functions lacking docstrings, tests, or type annotations.

Focus: Especially flags AI-attributed functions (from git blame heuristics).

Temporal Volatility (TVS)¶

What it detects: Files with anomalous change frequency, author diversity, or defect correlation.

Minimal example: A tiny helper such as normalizer.py gets patched almost every sprint while surrounding modules stay stable. That repeated churn suggests unclear ownership or an unstable abstraction.

Techniques: Statistical z-score on commit frequency, author entropy.

See the full user-facing reference page for TVS in the signal docs.

System Misalignment (SMS)¶

What it detects: Recently introduced imports or patterns foreign to their target module.

Example: A utility module suddenly importing from an HTTP client library.

Consistency Proxy Signals¶

Promoted from report-only to scoring-active in v0.7.0 with conservative initial weights. See ADR-007 for the original rationale.

Doc-Implementation Drift (DIA)¶

What it detects: Documented architecture that no longer matches actual code.

Weight: 0.04. Known precision limitations from URL/directory-name heuristics (63% strict precision in v0.5 baseline).

Broad Exception Monoculture (BEM)¶

What it detects: Modules where exception handling is uniformly broad (bare except, catch-all Exception) with high swallowing ratios.

Weight: 0.04.

Test Polarity Deficit (TPD)¶

What it detects: Test suites with near-zero negative assertions — only happy-path testing, no failure-path coverage.

Weight: 0.04.

Guard Clause Deficit (GCD)¶

What it detects: Modules where public functions uniformly lack early guard clauses (parameter validation, precondition checks).

Weight: 0.03.

Contract Signals¶

Added in v0.7.0/v0.7.1 via ADR-008.

Naming Contract Violation (NBV)¶

What it detects: Modules where naming conventions diverge from the established codebase patterns (e.g., inconsistent casing, prefix/suffix drift).

Weight: 0.04.

Bypass Accumulation (BAT)¶

What it detects: Modules accumulating bypass patterns (TODO/FIXME/HACK markers, disabled checks, hardcoded overrides) beyond a statistical threshold.

Weight: 0.03.

Exception Contract Drift (ECM)¶

What it detects: Modules where exception hierarchies or error-handling contracts diverge from the dominant codebase pattern.

Weight: 0.03.

Coupling Signal¶

Co-Change Coupling (CCC)¶

What it detects: File pairs that repeatedly change together in git history without explicit import dependency.

Example: order_service.py and payment_rules.py are changed together across many commits, but neither imports the other.

Techniques: Deterministic commit co-change aggregation with merge/bot down-weighting and static import-edge exclusion.

Weight: 0.005.