feat: scope dependency hygiene by workspace

Author: bntvllnt

docs/architecture.md

@@ -94,7 +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.
+- **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; dependency hygiene is scoped to the nearest package/workspace manifest.
 - **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.
 - **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.

docs/cli-reference.md

@@ -194,7 +194,7 @@ codebase-intelligence check <path> [--config <path>] [--format <fmt>] [--fail-on
 
 **Output:** pass/warn/fail verdict, findings, suppression ledger, and summary counts. Findings include stable `fingerprint`; cleanup findings may also include `kind`, `confidence`, and `evidence`. Summary counts include `suppressed` and `staleSuppressions`; `--summary` prints those counts when present. 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), `no-stale-suppressions` (warn), plus opt-in cleanup gates: `no-dead-files`, `no-unused-types`, `no-unused-members`, `no-unused-deps`. `ci-ignore-file`, `ci-ignore-next-line`, and JSDoc `@expected-unused` suppressions are reported as active/stale; JSDoc `@public` protects exported cleanup declarations while `@internal` remains checkable. Configure severities in `codebase-intelligence.json`.
+**Rules:** `no-comments` (off by default), `no-circular-deps` (error), `no-dead-exports` (warn), `no-stale-suppressions` (warn), plus opt-in cleanup gates: `no-dead-files`, `no-unused-types`, `no-unused-members`, `no-unused-deps`. Dependency findings are scoped to the nearest `package.json` / workspace manifest and include unused, unlisted, type-only, test-only, and runtime-from-devDependencies drift. `ci-ignore-file`, `ci-ignore-next-line`, and JSDoc `@expected-unused` suppressions are reported as active/stale; JSDoc `@public` protects exported cleanup declarations while `@internal` remains checkable. Configure severities in `codebase-intelligence.json`.
 
 ### init
 

docs/mcp-tools.md

@@ -186,7 +186,7 @@ Run the configurable rules engine and gate on findings.
 **Input:** `{}` (uses the loaded graph + discovered config)
 **Returns:** `{ verdict: "pass"|"warn"|"fail", summary: { error, warn, suppressed, staleSuppressions, rules }, configPath, suppressions[], 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). Each suppression records directive, status, file, line, targetLine, matched rule IDs, and suppressed count.
 
-Rules: `no-comments` (off by default), `no-circular-deps` (error), `no-dead-exports` (warn), `no-stale-suppressions` (warn), and opt-in cleanup gates `no-dead-files`, `no-unused-types`, `no-unused-members`, `no-unused-deps`. `ci-ignore-file`, `ci-ignore-next-line`, and JSDoc `@expected-unused` suppressions are reported as active/stale; JSDoc `@public` protects exported cleanup declarations while `@internal` remains checkable. 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), `no-stale-suppressions` (warn), and opt-in cleanup gates `no-dead-files`, `no-unused-types`, `no-unused-members`, `no-unused-deps`. Dependency findings are scoped to the nearest `package.json` / workspace manifest and include unused, unlisted, type-only, test-only, and runtime-from-devDependencies drift. `ci-ignore-file`, `ci-ignore-next-line`, and JSDoc `@expected-unused` suppressions are reported as active/stale; JSDoc `@public` protects exported cleanup declarations while `@internal` remains checkable. 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

@@ -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, suppression ledger, and summary counts. Built-in rules include no-comments, no-circular-deps, no-dead-exports, no-stale-suppressions, and opt-in no-dead-files, no-unused-types, no-unused-members, no-unused-deps. Reports active/stale `ci-ignore-*` and `@expected-unused` suppressions; `@public` protects exported cleanup declarations while `@internal` remains checkable.
+Gate modes: all, new-only. Returns pass/warn/fail verdict, findings, suppression ledger, and summary counts. Built-in rules include no-comments, no-circular-deps, no-dead-exports, no-stale-suppressions, and opt-in no-dead-files, no-unused-types, no-unused-members, no-unused-deps. Dependency findings are scoped to the nearest package/workspace manifest and include unused, unlisted, type-only, test-only, and runtime-from-devDependencies drift. Reports active/stale `ci-ignore-*` and `@expected-unused` suppressions; `@public` protects exported cleanup declarations while `@internal` remains checkable.
 
 ## Global Behavior
 

roadmap.md

@@ -160,6 +160,7 @@ Purpose: prove the CLI, MCP server, library outputs, docs, CI behavior, and agen
 | CH-P1-04 duplication families | As US-CLI-HUMAN, I can find duplicate logic with deterministic IDs. | Fixture exact clone + renamed clone + near-miss + below-threshold noise -> run CLI/MCP -> assert family IDs, thresholds, trace output, stable ordering, and no local-skip false positive. |
 | CH-P1-05 dead code expansion | As US-CLI-CI, I can gate unused files/types/members/deps without framework false positives. | Fixture unused file/type/member/dependency plus supported entrypoint -> run check JSON/SARIF -> assert real findings, confidence, and ignored entrypoint evidence. |
 | CH-P1-06 suppression hygiene | As US-MAINTAINER, suppressions do not hide stale debt forever. | Add active suppression -> assert finding suppressed and reported -> remove underlying finding -> assert stale suppression warning -> assert JSDoc `@public`/`@internal`/`@expected-unused` behavior. |
+| CH-P1-07 workspace dependency policy | As US-MONOREPO-MAINTAINER, dependency findings point at the package that owns the import. | Multi-package fixture -> run check JSON -> assert root/package manifests are scoped separately -> assert unlisted workspace imports, test-only deps, type-only deps, runtime devDeps, and unused deps with package evidence. |
 
 ### P2 Chains — Product Parity + Flagship Intelligence
 
@@ -328,12 +329,14 @@ Extend deletion intelligence beyond exported symbols.
 - 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.
+- Scope dependency hygiene to the nearest `package.json` / workspace manifest.
+- Detect runtime imports declared only in `devDependencies`.
 - 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.
+- Add CH-P1-07 coverage for root/package manifest scoping, unlisted package imports, test-only deps, type-only deps, runtime devDeps, and package evidence.
 
 **Remaining:**
 
-- 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

@@ -81,7 +81,7 @@
         },
         "no-unused-deps": {
           "$ref": "#/$defs/severity",
-          "description": "Report package.json dependencies that are never imported."
+          "description": "Report unused, unlisted, type-only, test-only, and wrong-section dependencies per package.json/workspace manifest."
         },
         "no-stale-suppressions": {
           "$ref": "#/$defs/severity",