Detector: Architecture Drift

Detector: Architecture Drift

Enforces import-graph layer boundaries declared in sentinel.toml.

Property	Value
Name	architecture-drift
Tier	DETERMINISTIC
Languages	Python
External tool	None
LLM required	No
Confidence	0.95 (forbidden), 0.90 (layer violation)

What it detects

Import statements that violate declared architecture boundary rules:

• Layer violations: a lower layer importing from a higher layer
• Forbidden imports: explicitly prohibited cross-module imports

How it works

1. Reads architecture rules from [sentinel.architecture] in sentinel.toml
2. Builds a layer rank map from the layers list (ordered highest → lowest)
3. Parses forbidden rules (e.g. "myapp.store -> myapp.web")
4. Walks all .py files, parses AST, extracts import edges
5. Checks each import against forbidden rules (HIGH severity) and layer ordering (MEDIUM severity)
6. Imports targeting shared modules are exempt from layer checks

Configuration

Requires architecture rules in sentinel.toml:

[sentinel.architecture]
layers = ["myapp.web", "myapp.core", "myapp.store"]   # highest → lowest
shared = ["myapp.models", "myapp.utils"]               # exempt from layer checks
forbidden = [
    "myapp.store -> myapp.web",
    "myapp.core -> myapp.cli",
]

Produces no findings if [sentinel.architecture] is not configured.

Severity

Type	Severity	Confidence
Forbidden import	HIGH	0.95
Layer violation	MEDIUM	0.90

Example finding

[ARCHITECTURE-DRIFT] src/myapp/store/db.py
  Module myapp.store.db (layer myapp.store, rank 2) imports from
  myapp.web.routes (layer myapp.web, rank 0). Lower layers should
  not import from higher layers.
  Severity: MEDIUM, Confidence: 0.90