Scope Drift

Overview

Scope drift is the most common type of agent drift. It occurs when an AI coding agent modifies files or directories that weren't part of your request. Caret detects scope drift by comparing every file the agent touches against the intent record's scope.

How scope is determined

Scope comes from three sources, in order of precision:

• Explicit scope: Files mentioned directly in the prompt: "Fix the bug in src/auth/login.ts"
• Inferred scope: Directories and files matched by keywords: "Fix the header component" matches src/components/Header.tsx
• Expanded scope: Files naturally related to in-scope files — imports, types, tests, barrel files

Detection algorithm

🖼 Scope visualization — file tree showing in-scope (green), adjacent (yellow), and out-of-scope (red) files

On every PreToolUse hook (file write), Caret evaluates scope:

1. Is the file in explicit scope? Score: 0 (allowed)
2. Is the file in inferred scope? Score: 0.1 (allowed, low drift)
3. Is the file adjacent (imports, types, tests)? Score: 0.3 (allowed, medium drift)
4. None of the above? Score: 0.7-1.0 depending on distance

Scoring

Factor	Score
Completely different directory tree	+0.8
Sibling directory	+0.5
Same directory, not mentioned	+0.3
Adjacent file (import chain, type dep)	+0.1
Config file (package.json, tsconfig)	+0.2

Alert fires when cumulative score exceeds threshold (default: 2.0).

Adjacency rules

These file relationships are scored lower:

• Component.tsx and Component.test.tsx
• Component.tsx and Component.module.css
• module.ts and index.ts (barrel re-export)
• Type files referenced by in-scope files
• package.json when dependencies change

Real-world examples

Benign (score: 0.4): "Add loading spinner to Dashboard" — agent creates Spinner.tsx and updates index.ts barrel. Expected expansion.

Moderate (score: 1.6): "Fix date formatting in activity feed" — agent fixes all date formatting consumers, not just the feed. Approaching threshold.

Severe (score: 4.2): "Change button color on settings page" — agent rewrites the Button component, Input, Card, and 4 other pages. Alert fired.

Configuration

{
  "detectors": {
    "scope_drift": {
      "enabled": true,
      "threshold": 2.0,
      "intervention": "alert",
      "ignore_patterns": ["*.lock", "*.generated.*"],
      "always_in_scope": ["package.json", "tsconfig.json"]
    }
  }
}

Tuning tips

• Lower threshold (1.0) for focused, well-scoped tasks
• Raise threshold (3.0+) for refactoring tasks that naturally touch many files
• Add common config files to always_in_scope to reduce false positives
• Use ignore_patterns for generated files and lock files