feat(drift): add content drift reports

README.md

@@ -57,7 +57,7 @@ claude mcp add -s user -t stdio codebase-intelligence -- npx -y codebase-intelli
 
 ## Features
 
-- **21 CLI commands** for architecture analysis, dependency impact, duplicate families, focused map/context packs, Highways convergence, improvement opportunities, dead code detection, search, CI rules, and agent setup
+- **22 CLI commands** for architecture analysis, dependency impact, duplicate families, focused map/context packs, content drift, Highways convergence, improvement opportunities, dead code detection, search, CI rules, and agent setup
 - **Machine-readable JSON output** (`--json`) for automation and CI pipelines
 - **Auto-cached index** in `.codebase-intelligence/` for fast repeat queries
 - **Cache migration facts** in JSON (`cacheDir`, `legacyCacheDir`, `migrated`, `gitignoreUpdated`, `warnings[]`)
@@ -66,10 +66,11 @@ claude mcp add -s user -t stdio codebase-intelligence -- npx -y codebase-intelli
 - **BM25 search** — ranked keyword search across files, symbols, and type/shape facts
 - **Process tracing** — detect entry points and execution flows through the call graph
 - **Codebase maps + context packs** — focused file/symbol/test graph with deterministic evidence IDs and token-bounded context for agents
+- **Content drift** — report-only detection for file/name/scope/side-effect/shape/test placement mismatch with stable evidence
 - **Highways analysis** — find repeated routes that bypass canonical dataflow paths and synthesize safe proposed highways
 - **Community detection** — Louvain clustering for natural file groupings
 - **Agent adoption** — `init` writes per-agent instruction files + installs a skill so AI agents query CI before grep/read
-- **MCP parity (secondary)** — same analysis and rules gate available as 22 MCP tools, 2 prompts, and 3 resources
+- **MCP parity (secondary)** — same analysis and rules gate available as 23 MCP tools, 2 prompts, and 3 resources
 
 ## Installation
 
@@ -113,6 +114,7 @@ codebase-intelligence <command> <path> [options]
 | `rename` | Reference discovery for rename planning |
 | `processes` | Entry-point execution flow tracing |
 | `map` | Focused codebase graph + token-bounded context pack |
+| `drift` | Report-only content drift findings with evidence and recommendations |
 | `highways` | Repeated route convergence, canonical path opportunities, and synthesis proposals |
 | `clusters` | Community-detected file clusters |
 | `check` | Rules-engine gate for CI, including opt-in dead-code and dependency gates |
@@ -126,13 +128,14 @@ codebase-intelligence <command> <path> [options]
 | `--force` | Rebuild index even if cache is valid |
 | `--limit <n>` | Limit results on supported commands |
 | `--metric <m>` | Select ranking metric for `hotspots` |
-| `--scope <s>` | Select git diff scope for `changes`: `staged`, `unstaged`, `all` |
+| `--scope <s>` | Select git diff scope for `changes`; directory/module scope for `map` and `drift` |
 | `--mode <m>` | Select clone mode for `duplicates`: `strict`, `mild`, `weak` |
 | `--min-tokens <n>` | Minimum duplicate token size for `duplicates` |
 | `--skip-local` | Ignore duplicate families confined to one file |
 | `--trace <id>` | Return token evidence for one duplicate family |
-| `--focus <name>` | Focus `map` on one symbol, file, or scope |
+| `--focus <name>` | Focus `map` or `drift` on one symbol, file, or scope |
 | `--context-budget <n>` | Bound `map` context pack size |
+| `--min-score <n>` | Minimum drift score for `drift` findings |
 | `--format <fmt>` | Export `map` as `markdown`, `json`, `dot`, or `graphml`; export `check` as `text`, `json`, or `sarif` |
 | `--operation <verb>` | Focus `highways` on one operation verb |
 | `--shape <name>` | Focus `highways` on one type/DTO shape |

docs/architecture.md

@@ -25,7 +25,7 @@ Core (shared computation)
   |     typed descriptors, input schemas, CLI/MCP adapters, result wrappers, text formatters
   v
 MCP (stdio)                    CLI (terminal/CI)
-  | 22 tools, 2 prompts,        | 21 commands with text + JSON
+  | 23 tools, 2 prompts,        | 22 commands with text + JSON
   | 3 resources for LLMs        | output for humans and CI
 ```
 
@@ -48,8 +48,9 @@ src/
   config/index.ts      <- Config discovery + zod validation
   rules/index.ts       <- Rules engine + registry (check command + MCP check tool)
   map/index.ts         <- Focused codebase maps + token-bounded context packs
+  drift/               <- Content drift scoring, profiles, findings, tokens, and stable evidence
   highways/index.ts    <- Repeated route convergence + bypass/cowpath/synthesis evidence
-  mcp/index.ts         <- 22 MCP tools for LLM integration
+  mcp/index.ts         <- 23 MCP tools for LLM integration
   mcp/hints.ts         <- Operation-keyed next-step hints for MCP tool responses
   impact/index.ts      <- Symbol-level impact analysis + rename planning
   search/index.ts      <- BM25 search engine
@@ -84,7 +85,7 @@ analyzeGraph(builtGraph, parsedFiles)
      }
 
 startMcpServer(codebaseGraph)
-  -> stdio MCP server with 22 tools, 2 prompts, 3 resources
+  -> stdio MCP server with 23 tools, 2 prompts, 3 resources
 
 runOperation(operation, codebaseGraph, input, context)
   -> { ok: true, data } | { ok: false, error, data? }
@@ -100,6 +101,7 @@ runOperation(operation, codebaseGraph, input, context)
 - **Suppression hygiene**: `check` reports active and stale `ci-ignore-*` / `@expected-unused` suppressions, emits stale suppression findings via `no-stale-suppressions`, and treats `@public` exported type declarations as intentional public API while `@internal` stays checkable.
 - **Highways H1/H2**: `highways` / `analyze_highways` enumerates entry-to-sink call routes, groups repeated routes by operation/shape/sink, detects bypasses and cowpaths around an existing canonical node, and with `--propose` synthesizes a read-only proposed highway with name, file, signature, skeleton, reroute plan, cycle safety, evidence, blast radius, recommendations, and a context pack for agents.
 - **Codebase map context packs**: `map` / `get_codebase_map` builds deterministic file/symbol/test/scope graphs with stable evidence IDs. `get_scope_graph` and `get_context_pack` are MCP-only filtered views derived from the same result, so agents get compact context without a second analyzer path.
+- **Content drift**: `drift` / `detect_content_drift` compares path/name/export intent with import/call/type/side-effect/test behavior. Findings are deterministic, evidence-backed, report-only, and baseline-gated before any future CI enforcement.
 - **Shared graph-load pipeline**: CLI commands and MCP stdio startup both use `src/graph-loader/` for path checks, legacy cache migration, cache reuse, parse/build/analyze, optional persistence, and stderr progress events.
 - **graphology**: In-memory graph with O(1) neighbor lookup. PageRank and betweenness computed via graphology-metrics.
 - **Batch git churn**: Single `git log --all --name-only` call, parsed for all files. Avoids O(n) subprocess spawning.

docs/cli-reference.md

@@ -1,6 +1,6 @@
 # CLI Reference
 
-21 commands for terminal and CI use. The 19 analysis commands have full parity with MCP tools and auto-cache the index to `.codebase-intelligence/`; `check` runs the rules gate; `init` sets up agent adoption.
+22 commands for terminal and CI use. The 20 analysis commands have full parity with MCP tools and auto-cache the index to `.codebase-intelligence/`; `check` runs the rules gate; `init` sets up agent adoption.
 
 ## Commands
 
@@ -180,6 +180,16 @@ codebase-intelligence map <path> [--focus <symbolOrFile>] [--scope <scope>] [--d
 
 **Output:** overview, focus node, nodes, edges, evidence, contextPack (ranked files, symbols, tests, token estimate/budget), and summary. JSON mode includes stable evidence IDs (`evidence-*`) and edge IDs (`edge-*`) for agent-safe references.
 
+### drift
+
+Report-only content drift findings for files whose names, folders, side effects, type shapes, or tests no longer match behavior.
+
+```bash
+codebase-intelligence drift <path> [--focus <fileOrSymbol>] [--scope <scope>] [--min-score <n>] [--json] [--force]
+```
+
+**Output:** `mode: "report-only"`, baseline status, findings with stable `drift-*` IDs, `kind` (`name-drift`, `scope-drift`, `mixed-responsibility`, `hidden-side-effect`, `shape-drift`, `orphan-scope`, `misplaced-test`), score, severity, declared intent, actual behavior, evidence IDs/summaries, recommendations, and advisory actions. Drift does not fail CI until a baseline/gate is configured.
+
 ### highways
 
 Find repeated routes that should converge on one canonical operation path.
@@ -249,15 +259,16 @@ codebase-intelligence init [path] [--agents <list>] [--all] [--skill] [--gitigno
 | `--min-tokens <n>` | duplicates | Minimum function body token count (default: 30) |
 | `--skip-local` | duplicates | Ignore families confined to one file |
 | `--trace <id>` | duplicates, highways | Return evidence for one family/opportunity id |
-| `--scope <s>` | changes, map | Git diff scope for `changes`; directory/module scope for `map` |
+| `--scope <s>` | changes, map, drift | Git diff scope for `changes`; directory/module scope for `map` and `drift` |
 | `--depth <n>` | dependents, map | Max traversal depth |
 | `--cohesion <n>` | forces | Min cohesion threshold (default: 0.6) |
 | `--tension <n>` | forces | Min tension threshold (default: 0.3) |
 | `--escape <n>` | forces | Min escape velocity threshold (default: 0.5) |
 | `--module <m>` | dead-exports | Filter by module path |
 | `--entry <name>` | processes | Filter by entry point name |
-| `--focus <name>` | map | Focus on one symbol, file, or scope |
+| `--focus <name>` | map, drift | Focus on one symbol, file, or scope |
 | `--context-budget <n>` | map | Approximate token budget for context pack |
+| `--min-score <n>` | drift | Minimum drift score to report |
 | `--operation <verb>` | highways | Focus on one operation verb |
 | `--shape <name>` | highways | Focus on one type/DTO shape |
 | `--min-routes <n>` | highways | Minimum routes reaching a sink before reporting |

docs/data-model.md

@@ -237,6 +237,65 @@ CodebaseContextPack {
 }
 ```
 
+## Content Drift Result
+
+`drift --json` and MCP `detect_content_drift` return deterministic, report-only drift findings. The command never fails CI by itself; a baseline/gate must be configured before drift can become enforcement.
+
+```typescript
+ContentDriftResult {
+  mode: "report-only"
+  baseline: {
+    status: "not-configured"
+    requiredForGate: true
+    reason: string
+  }
+  focus?: string
+  scope?: string
+  minScore: number
+  totalFindings: number
+  findings: ContentDriftFinding[]
+  evidence: ContentDriftEvidence[]
+  summary: string
+}
+
+ContentDriftFinding {
+  id: string
+  kind: "name-drift" | "scope-drift" | "mixed-responsibility" | "hidden-side-effect" | "shape-drift" | "orphan-scope" | "misplaced-test"
+  severity: "low" | "medium" | "high"
+  score: number
+  file: string
+  scope: string
+  title: string
+  recommendation: string
+  declaredIntent: {
+    path: string
+    fileName: string
+    scope: string
+    tokens: string[]
+    exports: string[]
+  }
+  actualBehavior: {
+    tokens: string[]
+    imports: string[]
+    calls: string[]
+    types: string[]
+    sideEffects: string[]
+    tests: string[]
+  }
+  evidenceIds: string[]
+  evidence: string[]
+  actions: Array<{ kind: string; command: string; description: string }>
+}
+
+ContentDriftEvidence {
+  id: string
+  kind: "name" | "scope" | "imports" | "calls" | "types" | "tests" | "metric"
+  summary: string
+  file?: string
+  symbol?: string
+}
+```
+
 ## Highways Result
 
 `highways --json` and MCP `analyze_highways` return deterministic route-convergence opportunities.

docs/mcp-tools.md

@@ -1,6 +1,6 @@
 # MCP Tools Reference
 
-22 tools available via MCP stdio.
+23 tools available via MCP stdio.
 
 Operation tools return JSON text payloads. Invalid operation inputs return `isError: true` with `{ "error": "..." }` using the same descriptor validation messages as CLI bad-argument exits.
 
@@ -199,7 +199,17 @@ Token-bounded context pack derived from `get_codebase_map`.
 **Use when:** Passing compact, ranked code context to an LLM.
 **Not for:** Visual graph export (use get_codebase_map).
 
-## 20. analyze_highways
+## 20. detect_content_drift
+
+Detect report-only mismatch between declared file/folder intent and observed behavior.
+
+**Input:** `{ focus?: string, scope?: string, minScore?: number }`
+**Returns:** mode, baseline, minScore, findings[] (id, kind, severity, score, file, scope, declaredIntent, actualBehavior, evidenceIds, evidence, recommendation, actions), evidence[], summary
+
+**Use when:** Finding file/folder/content drift before a refactor, roadmap cleanup, or baseline creation.
+**Not for:** Failing CI without a baseline (use check or a future ci wrapper).
+
+## 21. analyze_highways
 
 Detect repeated entry-to-sink routes that should converge on one canonical operation path.
 
@@ -209,7 +219,7 @@ Detect repeated entry-to-sink routes that should converge on one canonical opera
 **Use when:** Enforcing dataflow discipline, finding ad-hoc routes, or planning canonical shared paths.
 **Not for:** Raw execution flow listing (use get_processes).
 
-## 21. get_clusters
+## 22. get_clusters
 
 Community-detected clusters of related files.
 
@@ -219,7 +229,7 @@ Community-detected clusters of related files.
 **Use when:** "What files are related?" "Find natural groupings." Discovering emergent groupings that differ from directory structure.
 **Not for:** Directory-based modules (use get_module_structure).
 
-## 22. check
+## 23. check
 
 Run the configurable rules engine and gate on findings.
 
@@ -270,6 +280,7 @@ Rules: `no-comments` (off by default), `no-circular-deps` (error), `no-dead-expo
 | "What context should I give an LLM for this task?" | `get_context_pack` |
 | "Show a focused codebase graph" | `get_codebase_map` |
 | "Show only file/scope topology" | `get_scope_graph` |
+| "Which file names lie about behavior?" | `detect_content_drift` |
 | "Which routes bypass canonical dataflow?" | `analyze_highways` |
 | "What files naturally belong together?" | `get_clusters` |
 | "What are the main areas?" | `get_groups` |

llms-full.txt

@@ -31,8 +31,8 @@ Core (shared computation)
   |     typed descriptors, input schemas, CLI/MCP adapters, result wrappers, text formatters
   v
 MCP (stdio) + CLI
-  | MCP: 22 tools, 2 prompts, 3 resources for LLM agents
-  | CLI: 21 commands with formatted + JSON output for humans/CI
+  | MCP: 23 tools, 2 prompts, 3 resources for LLM agents
+  | CLI: 22 commands with formatted + JSON output for humans/CI
 ```
 
 ## Module Map
@@ -52,8 +52,9 @@ src/
   parser/duplication.ts <- Function-body clone token extraction
   duplication/index.ts <- Duplicate family detection + trace evidence
   map/index.ts         <- Focused codebase maps + token-bounded context packs
+  drift/               <- Content drift findings, profiles, tokens, and stable evidence
   highways/index.ts    <- Repeated route convergence + bypass/cowpath/synthesis evidence
-  mcp/index.ts         <- 22 MCP tools for LLM integration
+  mcp/index.ts         <- 23 MCP tools for LLM integration
   mcp/hints.ts         <- Operation-keyed next-step hints for MCP tool responses
   impact/index.ts      <- Symbol-level impact analysis + rename planning
   search/index.ts      <- BM25 search engine
@@ -310,7 +311,7 @@ The most dangerous files have: high churn + high coupling + low coverage.
 
 # MCP Tools Reference
 
-22 tools available via MCP stdio.
+23 tools available via MCP stdio.
 
 ## 1. codebase_overview
 High-level summary. Input: `{ depth?: number }`. Returns: totalFiles, totalFunctions, modules, topDependedFiles, metrics, and analysis mode/call graph precision.
@@ -369,13 +370,16 @@ File/scope/test topology from the same map result. Input: same as `get_codebase_
 ## 19. get_context_pack
 Token-bounded context pack from the same map result. Input: same as `get_codebase_map`. Returns: tokenBudget, tokenEstimate, rankedFiles, rankedSymbols, tests, evidenceIds, nextCommands.
 
-## 20. analyze_highways
+## 20. detect_content_drift
+Content drift. Input: `{ focus?: string, scope?: string, minScore?: number }`. Returns: report-only findings with stable IDs, kind, score, severity, declaredIntent, actualBehavior, evidence, recommendation, actions, and baseline status.
+
+## 21. analyze_highways
 Repeated route convergence. Input: `{ operation?: string, shape?: string, minRoutes?: number, propose?: boolean, trace?: string }`. Returns: bypass/cowpath/synthesis opportunities with route chains, evidence, blast radius, proposed canonical node, optional synthesis proposal, and context pack.
 
-## 21. get_clusters
+## 22. get_clusters
 Community-detected file clusters. Input: `{ minFiles?: number }`. Returns: clusters with cohesion.
 
-## 22. check
+## 23. check
 Rules-engine gate. Input: `{}`. Returns: pass/warn/fail verdict, findings, suppression ledger, config path, and summary counts. Findings always include ruleId, severity, file, line, column, message, and fingerprint; cleanup findings may also include kind, confidence, and evidence. Suppressions include directive, active/stale status, file, line, targetLine, ruleIds, and suppressed count.
 
 ## Tool Selection Guide
@@ -401,6 +405,7 @@ Rules-engine gate. Input: `{}`. Returns: pass/warn/fail verdict, findings, suppr
 | How does data flow? | get_processes |
 | What context should I give an LLM for this task? | get_context_pack |
 | Show a focused codebase graph | get_codebase_map |
+| Which file names lie about behavior? | detect_content_drift |
 | Which routes bypass canonical dataflow? | analyze_highways |
 | What files naturally belong together? | get_clusters |
 | What rule violations exist? | check |
@@ -409,7 +414,7 @@ Rules-engine gate. Input: `{}`. Returns: pass/warn/fail verdict, findings, suppr
 
 # CLI Reference
 
-21 commands — 19 analysis commands (full parity with MCP tools), `check` for CI rules, and `init` for agent adoption.
+22 commands — 20 analysis commands (full parity with MCP tools), `check` for CI rules, and `init` for agent adoption.
 
 ## Commands
 
@@ -515,6 +520,12 @@ codebase-intelligence map <path> [--focus <symbolOrFile>] [--scope <scope>] [--d
 ```
 Focused codebase graph plus token-bounded context pack. Formats: markdown, json, dot, graphml.
 
+### drift
+```bash
+codebase-intelligence drift <path> [--focus <fileOrSymbol>] [--scope <scope>] [--min-score <n>] [--json] [--force]
+```
+Report-only content drift findings. Returns stable `drift-*` IDs, drift kind, score/severity, declaredIntent, actualBehavior, evidence, recommendation, advisory actions, and baseline status.
+
 ### highways
 ```bash
 codebase-intelligence highways <path> [--operation <verb>] [--shape <name>] [--min-routes <n>] [--propose] [--trace <id>] [--json] [--force]

llms.txt

@@ -7,7 +7,7 @@
 - [Architecture](docs/architecture.md): Pipeline, module map, data flow, design decisions
 - [Data Model](docs/data-model.md): All TypeScript interfaces with field descriptions
 - [Metrics](docs/metrics.md): Per-file and module metrics, force analysis, complexity scoring
-- [MCP Tools](docs/mcp-tools.md): 22 MCP tools — inputs, outputs, use cases, selection guide
+- [MCP Tools](docs/mcp-tools.md): 23 MCP tools — inputs, outputs, use cases, selection guide
 - [CLI Reference](docs/cli-reference.md): CLI commands, flags, output formats, examples
 
 ## Quick Start
@@ -17,7 +17,7 @@ MCP mode (AI agents):
 codebase-intelligence ./path/to/project
 ```
 
-CLI mode (humans/CI) — 21 commands (19 analysis with MCP parity + `check` + `init`):
+CLI mode (humans/CI) — 22 commands (20 analysis with MCP parity + `check` + `init`):
 ```bash
 codebase-intelligence overview ./src
 codebase-intelligence hotspots ./src --metric coupling
@@ -36,6 +36,7 @@ codebase-intelligence impact ./src getUserById
 codebase-intelligence rename ./src oldName newName
 codebase-intelligence processes ./src --entry main
 codebase-intelligence map ./src --focus getUserById --context-budget 800 --json
+codebase-intelligence drift ./src --min-score 50 --json
 codebase-intelligence highways ./src --operation create --min-routes 3 --propose --json
 codebase-intelligence clusters ./src --min-files 3
 codebase-intelligence check ./src                      # rules gate for CI; JSON includes findings plus active/stale suppressions