Arch drift check

README.md

@@ -1,6 +1,6 @@
 # codegraph
 
-Codegraph is a small multi-language code analysis library and CLI for understanding repos quickly. It builds dependency graphs, symbol indexes, go-to-definition results, find-references results, semantic chunks, and PR review and impact artifacts across source languages plus graph-first document, stylesheet, and template formats.
+Codegraph is a small multi-language code analysis library and CLI for understanding repos quickly. It builds dependency graphs, symbol indexes, go-to-definition results, find-references results, semantic chunks, architecture drift reports, and PR review and impact artifacts across source languages plus graph-first document, stylesheet, and template formats.
 
 It is built for agent and human workflows that need repo structure fast without standing up a full editor or LSP stack.
 
@@ -141,6 +141,9 @@ node ./dist/cli.js apisurface
 
 # find duplicate and near-duplicate code
 node ./dist/cli.js duplicates ./src --min-confidence medium --limit 20
+
+# compare architecture drift between refs
+node ./dist/cli.js drift ./src --base origin/main --head HEAD --pretty
 ```
 
 If you install the published CLI instead of using a source checkout, replace `node ./dist/cli.js` with `codegraph`.
@@ -213,9 +216,11 @@ References for buildProjectIndex
 - tests/indexer.test.ts:22 call
 ```
 
-Use impact and review for PR or worktree risk:
+Use drift, impact, and review for architecture regression and PR or worktree risk:
 
 ```bash
+codegraph drift ./src --base origin/main --head HEAD --pretty
+codegraph drift ./src --base origin/main --head HEAD --fail-on new-cycle,public-api-removal
 codegraph impact --base origin/main --head HEAD --pretty
 codegraph review --base origin/main --head HEAD --summary
 ```
@@ -234,6 +239,8 @@ Review Summary
 Candidate tests: 4 (high: 1, medium: 2, low: 1)
 ```
 
+`drift` compares graph states over time. It reports structural signals such as new cycles, unresolved imports, public API removals, duplicate group count changes, hotspot jumps, and graph-edge changes; it is not runtime validation or compiler diagnostics.
+
 Run duplicate detection directly when refactor risk is the question:
 
 ```bash
@@ -256,7 +263,7 @@ codegraph duplicates ./src --min-confidence medium --limit 20
 }
 ```
 
-See [docs/cli.md](./docs/cli.md) for full flags, JSON shapes, duplicate scopes, and review output details.
+See [docs/cli.md](./docs/cli.md) for full flags, JSON shapes, drift policy gates, duplicate scopes, and review output details.
 
 ## Agent setup
 
@@ -292,11 +299,11 @@ Use the TypeScript API when another program needs deterministic file packs, revi
 import {
   buildProjectIndex,
   buildReviewReport,
+  analyzeArchitectureDrift,
   analyzeImpactFromDiff,
   analyzeImpactStreaming,
   tool_impactJSON,
 } from "@lzehrung/codegraph";
-
 const root = process.cwd();
 const index = await buildProjectIndex(root, { native: "auto" });
 
@@ -306,6 +313,13 @@ const review = await buildReviewReport(root, {
   reviewDepth: "standard",
 });
 
+const drift = await analyzeArchitectureDrift(root, {
+  provider: "git",
+  base: "origin/main",
+  head: "HEAD",
+  failOn: ["new-cycle", "public-api-removal"],
+});
+
 const impact = await analyzeImpactFromDiff(root, index, {
   provider: "git",
   base: "origin/main",

codegraph-skill/codegraph/SKILL.md

@@ -48,6 +48,7 @@ Then choose the narrowest follow-up command:
 - Worktree impact: `codegraph impact --provider git --base HEAD --head WORKTREE --pretty`
 - Review handoff: `codegraph review --base HEAD --head WORKTREE --summary`
 - Full review JSON: `codegraph review --base origin/main --head HEAD`
+- Architecture drift: `codegraph drift ./src --base origin/main --head HEAD --pretty`
 - Public API: `codegraph apisurface`
 - Duplicate cleanup: `codegraph duplicates --root . ./src --min-confidence medium`
 - Chunks: `codegraph chunk <file>`
@@ -64,6 +65,7 @@ Use Codegraph MCP tools when they are already available in the agent runtime. MC
 - Use `search` for anchors and `packet_get` for bounded evidence packets.
 - Use `refs`, `goto`, `deps`, `rdeps`, and `path` for semantic navigation.
 - Use `impact` and `review` for git-range risk analysis.
+- Use `drift` for base/head architecture-regression checks.
 - Use `query_sqlite` only for read-only artifact inspection.
 - Use `artifact_build` only when the tool is exposed and write access is intentionally enabled.
 
@@ -224,6 +226,11 @@ Prefer `refs` over plain text search when you want semantic usages rather than e
   `codegraph review --base origin/main --head HEAD`
 - Agent-ready full current worktree bundle:
   `codegraph review --base HEAD --head WORKTREE`
+- Architecture drift:
+  `codegraph drift ./src --base origin/main --head HEAD --pretty`
+- CI-selected drift gates:
+  `codegraph drift ./src --base origin/main --head HEAD --fail-on new-cycle,public-api-removal`
+  Drift compares structural architecture signals, not runtime behavior or compiler diagnostics. Duplicate increases are review or CI findings and only fail when selected by policy.
 
 Prefer impact `--pretty` first when the user asks what a change can break, what to test, or where a reviewer should focus. Use `review --summary` for compact model-readable handoffs, and use full review JSON when a script or tool step needs `projectFiles`, `graphDelta`, complete changed-symbol handles, or low-confidence fallback test candidates.
 

docs/agent-workflows.md

@@ -61,6 +61,15 @@ Search results include project-relative `handle`, `rankReasons`, `evidence`, `ne
 
 Use `artifact build` when the agent needs a durable handoff directory. The default bundle writes SQLite, self-describing project-relative graph JSON with symbols, a concise Markdown report, suggested questions, and a manifest. Suggested questions command stable handles, not ambiguous bare names, and use unique IDs even when display labels collide. In-repo artifact output directories and linked outside-root files are excluded from the emitted artifacts so stale handoff files do not feed back into the graph. With `--force`, Codegraph removes recognizable stale artifact files while preserving unrelated operator files and refusing unrecognized reserved-name collisions. `codegraph doctor <artifact-dir>` recognizes manifest-backed bundle directories and reports which expected artifacts are present.
 
+Use `drift` when the agent needs one architecture-regression report for a base/head range:
+
+```bash
+codegraph drift ./src --base origin/main --head HEAD --pretty
+codegraph drift ./src --base origin/main --head HEAD --fail-on new-cycle,public-api-removal
+```
+
+Drift compares structural signals over time: dependency cycles, hotspots, unresolved imports, API surface changes, duplicate group counts, and graph edges. It is review and CI evidence, not runtime validation or compiler diagnostics.
+
 ## MCP server
 
 Use `codegraph mcp serve --root . --stdio` when an agent can spawn a stdio MCP server, or `codegraph mcp serve --root . --port 7331` for Streamable HTTP at `/mcp`. HTTP binds to `127.0.0.1` by default; pass `--host <host>` only when the server must be reachable elsewhere. MCP reuses one in-process Codegraph session and exposes the same deterministic primitives as compact tools: `orient`, `packet_get`, `search`, `get_file`, `get_symbol`, `goto`, `refs`, `deps`, `rdeps`, `path`, `impact`, `review`, `query_sqlite`, and `artifact_build`.

docs/cli.md

@@ -158,6 +158,12 @@ codegraph duplicates --root . ./src ./packages/app --include-same-file
 codegraph duplicates ./src --raw-pairs
 codegraph duplicates --help
 
+# Compare architecture drift between git refs
+codegraph drift ./src --base origin/main --head HEAD --pretty
+codegraph drift ./src --base origin/main --head HEAD --json
+codegraph drift ./src --base origin/main --head HEAD --fail-on new-cycle,public-api-removal
+codegraph drift --base-artifact ./baseline/codegraph-out --head . --json
+
 # Go to definition
 codegraph goto <file> <line> <column>
 
@@ -185,7 +191,7 @@ codegraph grep --pattern 'eval\(' --ignore-case
 - Use `--include-same-file` for non-overlapping clones inside one file.
 - Use `--raw-pairs` when debugging the low-level pair evidence behind each group.
 
-`orient`, `packet`, `search`, `explain`, `artifact`, and `mcp` each support command-specific `--help` output.
+`orient`, `packet`, `search`, `explain`, `artifact`, `drift`, and `mcp` each support command-specific `--help` output.
 
 #### Agent orientation and packets
 
@@ -319,6 +325,15 @@ codegraph review --base origin/main --head HEAD --summary --duplicates impacted
 codegraph graph-delta --git-base origin/main --git-head HEAD > graph-delta.json
 ```
 
+```bash
+# Architecture drift with CI policy gates
+codegraph drift ./src --base origin/main --head HEAD --pretty
+codegraph drift ./src --base origin/main --head HEAD --fail-on new-cycle,unresolved-import,public-api-removal
+codegraph drift --base-artifact ./baseline/codegraph-out --head . --json
+```
+
+`drift` compares architecture signals, not runtime behavior, compiler diagnostics, or style. Duplicate drift compares group counts and stable top group keys; duplicate increases are review or CI findings and only fail the process when selected by `--fail-on`.
+
 For git-provider impact, `--head` accepts normal revisions plus worktree sentinels. Use `WORKTREE` to compare the base revision against the current working tree, including staged and unstaged tracked-file changes. Use `STAGED` or `INDEX` to compare the base revision against the current index; with `--base HEAD`, that is staged changes only. Untracked files are not included until they are staged or otherwise tracked by Git.
 
 Impact JSON responses include `schemaVersion` plus `format: "full" | "compact"` so downstream tools can branch on payload shape without inferring it from missing fields. Use `--compact` or `--compact-json` for compact impact JSON. Impact JSON can also include `exportSummary`, `reexportChains`, `topImpacts`, `surfaceArea`, `clusters`, and `changedSymbols[].callCompatibility` when applicable. File paths in impact reports are project-relative, and raw diffs that point outside the project root are rejected.

docs/library-api.md

@@ -575,6 +575,24 @@ const references = await tool_findReferences(root, "src/main.ts", 10, 5, index);
 const impact = await tool_impactJSON(root, { provider: "git", base: "HEAD", head: "WORKTREE" }, { index });
 ```
 
+### Architecture drift
+
+Use `analyzeArchitectureDrift()` when a caller needs one deterministic architecture-regression report instead of separately comparing cycles, unresolved imports, API surface, duplicates, hotspots, and graph edges.
+
+```ts
+import { analyzeArchitectureDrift } from "@lzehrung/codegraph";
+
+const report = await analyzeArchitectureDrift(process.cwd(), {
+  provider: "git",
+  base: "origin/main",
+  head: "HEAD",
+  includeRoots: ["src"],
+  failOn: ["new-cycle", "public-api-removal"],
+});
+```
+
+The API returns `ArchitectureDriftReport` with `schemaVersion: 1`, base/head summaries, bounded findings, and policy state. Drift compares architecture signals only; it does not run code, typecheck, or lint.
+
 ### Programmatic review and impact output
 
 Use the exported TypeScript APIs when another program is composing deterministic review packets, file packs, or model prompts. CLI `--pretty` and `--summary` output is optimized for compact reading by people or models; it is not the stable integration contract.