feat: add dead code expansion gates

README.md

@@ -111,7 +111,7 @@ codebase-intelligence <command> <path> [options]
 | `rename` | Reference discovery for rename planning |
 | `processes` | Entry-point execution flow tracing |
 | `clusters` | Community-detected file clusters |
-| `check` | Rules-engine gate for CI |
+| `check` | Rules-engine gate for CI, including opt-in dead-code and dependency gates |
 | `init` | Set up AI agents to use CI — writes per-agent instruction files (skill opt-in via `--skill`) |
 
 ### Useful flags

docs/architecture.md

@@ -94,6 +94,7 @@ runOperation(operation, codebaseGraph, input, context)
 - **Operation registry foundation**: Analysis operations now have typed descriptors in `src/operations/` with operation names, CLI command names, MCP tool names, input schemas, discriminated run results, and result-object text formatters. MCP tool registration and CLI command execution consume those descriptors; CLI JSON remains raw result data plus cache facts.
 - **Type/Shape facts**: Full-program parsing stores compact parameter/return/type-parameter facts on parsed symbols. `file`, `symbol`, and `search` JSON expose those facts additively; search indexes consumed/produced shape tokens so agents can ask which symbols touch a shape without a new command.
 - **Duplication families**: Parser stores deterministic function-body token streams on symbols. `duplicates` / `find_duplicates` groups symbols into strict, renamed, and near-miss clone families, with optional trace evidence for AI agents before refactors.
+- **Dead-code gates**: `check` can opt into unused-file, unused-type, unused-member, and dependency hygiene rules. These rules use graph metrics plus local TypeScript AST facts and emit confidence/evidence in JSON and SARIF.
 - **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

@@ -192,7 +192,9 @@ codebase-intelligence check <path> [--config <path>] [--format <fmt>] [--fail-on
 
 **Gate modes:** `all` (default), `new-only`.
 
-**Output:** pass/warn/fail verdict, findings, and summary counts. Exit code `0` on pass, `1` when the configured gate fails, `2` for invalid config or arguments.
+**Output:** pass/warn/fail verdict, findings, and summary counts. Findings include stable `fingerprint`; cleanup findings may also include `kind`, `confidence`, and `evidence`. Exit code `0` on pass, `1` when the configured gate fails, `2` for invalid config or arguments.
+
+**Rules:** `no-comments` (off by default), `no-circular-deps` (error), `no-dead-exports` (warn), plus opt-in cleanup gates: `no-dead-files`, `no-unused-types`, `no-unused-members`, `no-unused-deps`. Configure severities in `codebase-intelligence.json`.
 
 ### init
 

docs/data-model.md

@@ -170,3 +170,26 @@ CacheFacts {
   warnings: string[]        // Non-fatal legacy/cache state warnings
 }
 ```
+
+## Check Findings
+
+`check --json` and MCP `check` return deterministic findings. `kind`, `confidence`,
+and `evidence` are additive fields for rules that can explain cleanup confidence.
+
+```typescript
+Finding {
+  ruleId: string
+  severity: "warn" | "error"
+  kind?: string
+  confidence?: "high" | "medium" | "low"
+  file: string
+  line: number
+  column: number
+  endLine?: number
+  endColumn?: number
+  message: string
+  evidence?: string[]
+  actions?: FindingAction[]
+  fingerprint: string
+}
+```

docs/mcp-tools.md

@@ -184,9 +184,9 @@ Community-detected clusters of related files.
 Run the configurable rules engine and gate on findings.
 
 **Input:** `{}` (uses the loaded graph + discovered config)
-**Returns:** `{ verdict: "pass"|"warn"|"fail", summary: { error, warn, rules }, configPath, findings[] }`. Each finding has ruleId, severity, file, line, column, message, fingerprint, and optional advisory `actions[]` (the tool is read-only — actions are hints, never applied).
+**Returns:** `{ verdict: "pass"|"warn"|"fail", summary: { error, warn, rules }, configPath, findings[] }`. Each finding has ruleId, severity, file, line, column, message, fingerprint, optional `kind`, optional `confidence`, optional `evidence[]`, and optional advisory `actions[]` (the tool is read-only — actions are hints, never applied).
 
-Rules: `no-comments` (off by default), `no-circular-deps` (error), `no-dead-exports` (warn). Configure severities and options in `codebase-intelligence.json` (validated by `schema.json`).
+Rules: `no-comments` (off by default), `no-circular-deps` (error), `no-dead-exports` (warn), and opt-in cleanup gates `no-dead-files`, `no-unused-types`, `no-unused-members`, `no-unused-deps`. Configure severities and options in `codebase-intelligence.json` (validated by `schema.json`).
 
 **Use when:** Linting a codebase or enforcing a CI gate. "What rule violations exist?"
 **Not for:** Architecture metrics (use analyze_forces).

llms-full.txt

@@ -315,7 +315,7 @@ Entry point execution flows. Input: `{ entryPoint?: string, limit?: number }`. R
 Community-detected file clusters. Input: `{ minFiles?: number }`. Returns: clusters with cohesion.
 
 ## 18. check
-Rules-engine gate. Input: `{}`. Returns: pass/warn/fail verdict, findings, config path, and summary counts.
+Rules-engine gate. Input: `{}`. Returns: pass/warn/fail verdict, findings, 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.
 
 ## Tool Selection Guide
 
@@ -470,7 +470,7 @@ content between the `codebase-intelligence:start`/`:end` markers is ever touched
 codebase-intelligence check <path> [--config <path>] [--format <fmt>] [--fail-on <severity>] [--gate <mode>] [--base <ref>] [--quiet] [--summary] [--json] [--force]
 ```
 Rules-engine gate for CI. Formats: text, json, sarif. Fail-on: error, warn, never.
-Gate modes: all, new-only. Returns pass/warn/fail verdict, findings, and summary counts.
+Gate modes: all, new-only. Returns pass/warn/fail verdict, findings, and summary counts. Built-in rules include no-comments, no-circular-deps, no-dead-exports, and opt-in no-dead-files, no-unused-types, no-unused-members, no-unused-deps.
 
 ## Global Behavior
 

llms.txt

@@ -36,7 +36,7 @@ codebase-intelligence impact ./src getUserById
 codebase-intelligence rename ./src oldName newName
 codebase-intelligence processes ./src --entry main
 codebase-intelligence clusters ./src --min-files 3
-codebase-intelligence check ./src                      # rules gate for CI
+codebase-intelligence check ./src                      # rules gate for CI; JSON findings may include kind/confidence/evidence
 codebase-intelligence init .                         # make AI agents use CI
 ```
 

roadmap.md

@@ -321,13 +321,21 @@ Add deterministic clone detection on the existing parser path.
 
 Extend deletion intelligence beyond exported symbols.
 
-**To do:**
+**Foundation slice:**
+
+- Add opt-in `check` rules: `no-dead-files`, `no-unused-types`, `no-unused-members`, `no-unused-deps`.
+- Detect unimported non-entrypoint files with confidence/evidence.
+- Detect local unused type/interface declarations and exported dead types outside supported entrypoints.
+- Detect unused private class members and non-exported enum members.
+- Detect unused, unlisted, type-only, and test-only package dependencies.
+- Emit `kind`, `confidence`, and `evidence[]` in JSON and SARIF findings.
+- Add CH-P1-05 coverage for JSON/SARIF, supported package entrypoint ignore, and all four dead-code categories.
+
+**Remaining:**
 
-- Detect unused files.
-- Detect unused types.
-- Detect unused enum/class members.
-- Detect unused / unlisted / type-only / test-only dependencies.
-- Keep findings framework-aware to avoid false positives.
+- Add stale suppression reporting and `@public` / `@expected-unused` semantics in CH-P1-06.
+- Add workspace/package-section dependency policy beyond single-package `package.json`.
+- Add CSS/template/framework plugin coverage only after `doctor` can explain supported surfaces.
 
 ### Suppression Hygiene
 

schema.json

@@ -69,7 +69,15 @@
         },
         "no-dead-files": {
           "$ref": "#/$defs/severity",
-          "description": "Report files unreachable from any entry point."
+          "description": "Report unimported files that are not recognized entrypoints."
+        },
+        "no-unused-types": {
+          "$ref": "#/$defs/severity",
+          "description": "Report local type/interface declarations and exported type declarations that appear unused."
+        },
+        "no-unused-members": {
+          "$ref": "#/$defs/severity",
+          "description": "Report unused private class members and non-exported enum members."
         },
         "no-unused-deps": {
           "$ref": "#/$defs/severity",

src/cli.ts

@@ -788,7 +788,7 @@ function parseGate(value: string | undefined): "all" | "new-only" | undefined |
 
 program
   .command("check")
-  .description("Run the rules engine and gate on findings (comments, circular deps, dead exports)")
+  .description("Run the rules engine and gate on findings")
   .argument("<path>", "Path to TypeScript codebase")
   .option("--config <path>", "Config file path (overrides discovery)")
   .option("--format <fmt>", "Output: text, json, or sarif (default: text)")