Skip to content

Destynova2/cli-code-skills / cli-audit-drift

cli-audit-drift

Verified

Detect silent semantic drift between intended behavior (CONTRACTS.md) and actual implementation. Scans code against functional contracts, invariants, and known drift history to catch behavioral changes that compile and run but violate the original intention. Use when reviewing code changes, before commits, auditing behavioral conformity, or saying 'check drift', 'contract check', 'intention vs implementation', 'semantic drift', 'is this still correct', 'does this match the spec', 'behavioral regression', 'silent bug', 'autophagy scan'. Also triggers on 'CONTRACTS.md', 'invariant check', 'intention audit', 'contract violation'.

references/drift-detection-rules.md

View on GitHub
# Drift Detection Rules

> **When to read:** During Step 3 (scan for drift) to systematically check each contracted function.

---

## Contents

- Detection workflow per function
- Classification decision tree
- Severity scoring
- Common drift patterns by domain

---

## Detection workflow per function

For each contracted function, execute these checks in order:

### Check 1 — Structural comparison

Compare the current implementation structure against the contract:

1. **Count code paths:** How many branches/returns does the function have?
2. **Map parameters to usage:** Is every declared parameter used? Are there undeclared parameters (globals, env)?
3. **Check return type:** Does it match what the contract implies?

**Drift if:** The function has more code paths than the contract's intention suggests (hidden special cases).

### Check 2 — Invariant verification

For each invariant in the contract:

1. **Read the invariant** (e.g., "INV-1: mask treats all fields identically")
2. **Identify the code** that should enforce it
3. **Search for violations** using the red flag patterns from `invariant-patterns.md`
4. **Grade confidence:**
   - **Certain violation:** code explicitly contradicts invariant (e.g., `if field == "b"`)
   - **Probable violation:** code has a pattern that usually breaks this invariant
   - **Suspicious:** code is complex enough that the invariant might not hold, but can't confirm without running

### Check 3 — Red flag scan

Grep the function body for every pattern listed in the contract's "Red flags" section.

**Any match is a finding.** Even if it turns out to be correct (intentional evolution), it must be reported and classified.

### Check 4 — Git history analysis

```bash
git log --oneline -20 -- {file_containing_function}
git diff HEAD~5 -- {file_containing_function}
```

Look for:
- Recent changes to the function (especially last 5 commits)
- Changes that touch the invariant-sensitive parts (conditionals, return values)
- Changes without corresponding test updates
- Changes without corresponding contract updates

**Drift if:** Function was changed recently but CONTRACTS.md was not updated.

### Check 5 — Call chain propagation

If the contracted function calls other contracted functions:

1. List the call chain
2. Check if any callee has a known drift (from its own contract)
3. Assess if the callee's drift propagates to the caller

**Drift if:** A dependency has drifted and the caller doesn't guard against it.

### Check 6 — Orphan code detection (ubiquitin scan)

The reverse of Check 5: instead of looking for code that drifted from its contract, look for **code whose contract has been removed but whose implementation remains**. This is the cellular equivalent of a misfolded protein that nobody bothered to ubiquitinate.

1. **List currently contracted function names** from CONTRACTS.md
2. **Inspect git history of the contracts file:** `git log -p -- CONTRACTS.md` (and `docs/CONTRACTS.md`, `contracts/`) over the last 6 months
3. **For each contract that was removed**, check whether its implementation still exists:
   - Grep for the function name across the codebase
   - If found, locate its definition and check if it is still called from anywhere
4. **Classify the finding:**
   - Implementation exists and is called → orphan code that may still be load-bearing → propose either re-introducing the contract or removing the call sites + the function
   - Implementation exists but has zero callers → dead orphan → propose explicit deletion
   - Implementation no longer exists → clean (the deletion was performed when the contract was removed)

**Drift if:** A contract was deleted from CONTRACTS.md but the corresponding implementation still lives in the codebase.

**Why it matters:** without explicit deletion, orphan code accumulates as toxic tech debt. The next developer cannot tell whether the function is still load-bearing, is dead, or is half-migrated. Garbage collectors do not catch this — only an active tag (like ubiquitin) does. Skipping this check is how codebases silently accumulate "zombie" functions that compile, run, and confuse every reviewer for years.

---

## Classification decision tree

```
Does a current contract reference this code?
├── No (contract was removed but implementation remains) → ORPHAN CODE (propose ubiquitin tag = explicit deletion)
└── Yes →
    Is the code behavior different from the contract?
    ├── No → CLEAN (no drift)
    └── Yes →
        Was there a recent code change?
        ├── Yes →
        │   Is there a corresponding requirement/ticket?
        │   ├── Yes → EVOLUTION (contract needs update)
        │   └── No → MISS (unintentional, propose minimal re-fold from contract)
        └── No →
            Was the contract recently added/updated?
            ├── Yes → STALE CODE (code predates the contract, never matched)
            └── No →
                Is the contract vague enough to allow the current behavior?
                ├── Yes → AMBIGUITY (contract needs clarification)
                └── No → MISS (long-standing bug, propose minimal re-fold from contract)
```

---

## Severity scoring

| Severity | Criteria | Examples |
|----------|---------|---------|
| **Critical** | Security invariant violated, data corruption possible, financial calculation wrong | Masking function that leaks data, price calculation that drops cents |
| **High** | Core business logic drift, user-facing behavioral change | Order status transition that skips validation, filter that drops items |
| **Medium** | Internal inconsistency, edge case not covered | Formatter that trims whitespace unexpectedly, parser that chokes on unicode |
| **Low** | Cosmetic drift, logging difference, non-user-facing | Different error message format, log level change |

---

## Common drift patterns by domain

### API endpoints
- Response shape changes (new fields, removed fields, renamed fields)
- Status code changes (200 → 201, 400 → 422)
- Error response format changes
- Pagination behavior changes (offset vs cursor, default page size)
- Authentication/authorization logic changes

### Business logic
- Calculation formula changes (rounding, precision, order of operations)
- Validation rule changes (looser or stricter)
- Default value changes
- Feature flag behavior (flag removed but code path remains)
- Edge case handling changes (null, empty, zero)

### Data layer
- Query behavior changes (ordering, filtering, joins)
- Migration that changes semantics (column rename ≠ column re-purpose)
- Cache invalidation behavior changes
- Transaction boundary changes (what's atomic, what's not)

### Security
- Authentication bypass paths (new endpoint without auth middleware)
- Authorization escalation (role check removed or loosened)
- Input validation removed or weakened
- Encryption/hashing algorithm changes
- Token lifetime/scope changes
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall