Enhance drift summaries and controls

README.md

@@ -143,7 +143,8 @@ node ./dist/cli.js apisurface
 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
+node ./dist/cli.js drift ./src --base origin/main --head HEAD --compact-json
+node ./dist/cli.js drift ./src --base origin/main --head HEAD --pretty --graph-edges summary --public-api removals
 ```
 
 If you install the published CLI instead of using a source checkout, replace `node ./dist/cli.js` with `codegraph`.
@@ -219,8 +220,8 @@ References for buildProjectIndex
 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 drift ./src --base origin/main --head HEAD --pretty --graph-edges summary --public-api removals
+codegraph drift ./src --base origin/main --head HEAD --compact-json
 codegraph impact --base origin/main --head HEAD --pretty
 codegraph review --base origin/main --head HEAD --summary
 ```
@@ -239,7 +240,7 @@ 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.
+`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. Use `--graph-edges summary|off`, `--public-api removals|off`, and `--compact-json` to keep CI and review output bounded.
 
 Run duplicate detection directly when refactor risk is the question:
 
@@ -318,6 +319,9 @@ const drift = await analyzeArchitectureDrift(root, {
   base: "origin/main",
   head: "HEAD",
   failOn: ["new-cycle", "public-api-removal"],
+  format: "compact",
+  graphEdges: "summary",
+  publicApi: "removals",
 });
 
 const impact = await analyzeImpactFromDiff(root, index, {

codegraph-skill/codegraph/SKILL.md

@@ -48,7 +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`
+- Architecture drift: `codegraph drift ./src --base origin/main --head HEAD --pretty --graph-edges summary --public-api removals`
 - Public API: `codegraph apisurface`
 - Duplicate cleanup: `codegraph duplicates --root . ./src --min-confidence medium`
 - Chunks: `codegraph chunk <file>`
@@ -227,10 +227,12 @@ Prefer `refs` over plain text search when you want semantic usages rather than e
 - Agent-ready full current worktree bundle:
   `codegraph review --base HEAD --head WORKTREE`
 - Architecture drift:
-  `codegraph drift ./src --base origin/main --head HEAD --pretty`
+  `codegraph drift ./src --base origin/main --head HEAD --pretty --graph-edges summary --public-api removals`
+- Compact CI drift output:
+  `codegraph drift ./src --base origin/main --head HEAD --compact-json`
 - 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.
+  Drift compares structural architecture signals, not runtime behavior or compiler diagnostics. Use `--graph-edges` and `--public-api` to trim noisy findings without changing policy evaluation.
 
 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

@@ -64,11 +64,11 @@ Use `artifact build` when the agent needs a durable handoff directory. The defau
 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
+codegraph drift ./src --base origin/main --head HEAD --pretty --graph-edges summary --public-api removals
+codegraph drift ./src --base origin/main --head HEAD --compact-json
 ```
 
-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.
+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. Use compact JSON for CI or agent handoff, and use graph-edge/API filters to keep human review output bounded.
 
 ## MCP server
 

docs/cli.md

@@ -159,8 +159,9 @@ 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 --pretty --graph-edges summary --public-api removals
 codegraph drift ./src --base origin/main --head HEAD --json
+codegraph drift ./src --base origin/main --head HEAD --compact-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
 
@@ -327,12 +328,18 @@ 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 --pretty --graph-edges summary --public-api removals
+codegraph drift ./src --base origin/main --head HEAD --compact-json
 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`.
+`drift` compares architecture signals, not runtime behavior, compiler diagnostics, or style.
+
+- `--graph-edges full|summary|off` controls whether graph-edge churn is emitted per edge, summarized by source file, or suppressed.
+- `--public-api all|removals|off` controls whether API additions are shown; removals stay the main review signal.
+- `--compact-json` emits bounded machine-friendly JSON with summary counts and example findings.
+- Duplicate drift compares group counts plus stable top-group deltas; 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.
 

docs/library-api.md

@@ -588,9 +588,19 @@ const report = await analyzeArchitectureDrift(process.cwd(), {
   head: "HEAD",
   includeRoots: ["src"],
   failOn: ["new-cycle", "public-api-removal"],
+  graphEdges: "summary",
+  publicApi: "removals",
+  format: "compact",
 });
 ```
 
+Drift callers can tune noise and payload size without changing the core comparison:
+
+- `graphEdges: "full" | "summary" | "off"` controls graph-edge churn detail.
+- `publicApi: "all" | "removals" | "off"` controls whether API additions are emitted.
+- `format: "compact"` emits bounded example findings plus `summary.byKind` and `summary.bySeverity`.
+- Git-backed reports expose logical `base.ref` and `head.ref` values instead of temporary checkout paths.
+
 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