Skip to content

Temporal Volatility Signal (TVS)

Signal ID: TVS
Full name: Temporal Volatility Score
Type: Report-only signal (weight 0.0 — does not contribute to drift score)
Default weight: 0.0
Scope: git_dependent

What TVS detects

TVS detects files with abnormal churn relative to their size and role. It looks for hotspots that keep changing while the surrounding code stays comparatively stable — often a sign of unclear ownership, weak abstractions, or AI-generated code that is being patched repeatedly.

Minimal code example

Imagine a small helper that should be boring and stable:

# src/utils/normalizer.py

def normalize_email(value: str) -> str:
    return value.strip().lower()

If that same helper is edited in commit after commit — one week to trim dots, the next to preserve plus-addresses, then again to patch edge cases — while neighboring modules barely move, TVS treats it as a volatility hotspot. The issue is not that the file changed once; it is that the file keeps absorbing uncertainty.

Example finding

temporal_volatility in src/utils/normalizer.py
  Change frequency: 12 commits in 30 days (z-score: 2.4)
  Unique authors: 5  |  AI-attributed: 60%
  Defect-correlated commits: 3/12
  → Score: 0.72 (HIGH)

This points to a small file that is being revisited disproportionately often compared with the rest of the repository.

Why temporal volatility matters

  • Hotspots predict future bugs — files that change frequently and attract bug fixes are likely to continue doing so.
  • Multi-author churn erodes conventions — each author (human or AI) may apply different patterns.
  • High AI attribution + high churn = "vibe-coding loop" — rapid AI-generated changes without stabilization.
  • Trend indicator — TVS findings that persist across scans highlight structurally unstable areas.

How the score is calculated

TVS combines four sub-metrics using z-score normalization:

  1. Change frequency — commits per 30-day window, compared to repository average.
  2. Author entropy — Shannon entropy of contributing authors (high entropy = many authors).
  3. Defect correlation — proportion of commits associated with bug fixes.
  4. AI attribution ratio — proportion of commits attributed to AI tools.
\[ \text{volatility\_score} = w_1 \cdot z(\text{frequency}) + w_2 \cdot \text{entropy} + w_3 \cdot \text{defect\_ratio} + w_4 \cdot \text{ai\_ratio} \]

Modules exceeding volatility_z_threshold (default: 1.5 standard deviations) are flagged.

Severity thresholds:

Score range Severity
≥ 0.7 HIGH
≥ 0.5 MEDIUM
≥ 0.3 LOW
< 0.3 INFO

How to address TVS findings

  1. Extract the volatile logic behind a stable interface — if one helper keeps changing, move the unstable rules into a dedicated module with clear boundaries.
  2. Assign ownership — high author entropy often means no one is really responsible for keeping the file coherent.
  3. Add tests before the next patch — repeated bug-fix commits usually mean the behavior is still underspecified.
  4. Review AI-generated changes more carefully — volatile, AI-attributed files deserve extra scrutiny before merge.
  5. Treat TVS as a triage signal — it tells you where to look first, not that the file is automatically wrong.

Configuration

# drift.yaml
weights:
  temporal_volatility: 0.0   # report-only (set > 0.0 to make scoring-active)

thresholds:
  volatility_z_threshold: 1.5   # z-score threshold for flagging
  recency_days: 14              # focus window for recent activity

TVS is report-only by default because it requires git history and its precision/recall have not yet been validated across diverse repositories. Set weight > 0.0 to include TVS in the drift score.

Detection details

  1. Load git history — parse commits from the last since days (default: 90).
  2. Build file histories — per-file commit counts, author lists, AI attribution.
  3. Compute per-module metrics — aggregate file-level metrics to directory level.
  4. Z-score normalization — compare each module to the repository-wide distribution.
  5. Flag outliers — modules exceeding the z-score threshold.

TVS requires git history (git_dependent=True). Without access to a git repository, TVS produces no findings.

  • CCC (Co-Change Coupling) — detects files that change together. TVS identifies volatile individual modules; CCC identifies coupled pairs.
  • ECM (Exception Contract Drift) — also git-dependent, tracking behavioral changes across commits.
  • SMS (System Misalignment) — detects convention violations. Volatile modules (TVS) are more likely to contain misaligned code (SMS).