scip-query 0.10.0 → 0.10.2

package/docs/COMMAND_REFERENCE.md

@@ -0,0 +1,131 @@
+# Command Reference
+
+<!-- BEGIN GENERATED COMMAND REFERENCE -->
+
+This syntax summary is generated from the CLI command descriptors. Keep workflow guidance hand-authored, but keep command syntax, descriptions, and option flags descriptor-owned.
+
+### Indexing
+
+| Command | Description | Options |
+|---|---|---|
+| `reindex` | Index the codebase and convert to SQLite | `-l, --language <lang>`<br>`--pnpm-workspaces`<br>`--force`<br>`--allow-partial`<br>`--indexer-concurrency <n>` |
+| `augment-sources` | Add source files skipped by upstream SCIP indexers to the SQLite documents table | - |
+| `augment-vue` | Add compiler-resolved Vue SFC references to the SQLite index using Volar | `--project <tsconfig>` |
+
+### Core
+
+| Command | Description | Options |
+|---|---|---|
+| `stats` | Show index statistics | `--json` |
+
+### Navigation
+
+| Command | Description | Options |
+|---|---|---|
+| `files <pattern>` | Find files matching a pattern | `--json` |
+| `methods <className>` | List methods of a class (with line ranges) | `--json` |
+| `refs <symbol>` | Find all files referencing a symbol | `--full`<br>`--json` |
+| `trace <symbol>` | Trace a symbol: definition + all references | `--full`<br>`--json` |
+| `deps <file>` | Files this file depends on (internal) | `--json` |
+| `rdeps <file>` | Files that depend on this file/module | `--json` |
+| `system <module>` | Full module map: files, symbols, deps in/out | `--json` |
+| `surface <module>` | What symbols consumers actually use from this module | `--json` |
+| `imports <file>` | What symbols does this file import? | `--full`<br>`--json` |
+| `imported-by <symbol>` | Which files import this symbol? | `--json` |
+| `outline <file>` | Tree view of symbols in a file, with line ranges | `--signatures`<br>`--json` |
+| `members <symbol>` | All children of a symbol (methods, fields, nested types) | `--json` |
+| `by-kind <kind>` | Find symbols by SCIP kind (class, interface, enum, function, etc.) | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+| `kind-counts` | Histogram of symbol kinds in the codebase | `-s, --scope <path>`<br>`--json` |
+| `hierarchy <symbol>` | Show a symbol's ancestry chain (method → class → module) | `--json` |
+| `code <symbol>` | Read the source code for a symbol (bounded to its definition range) | `-C, --context <n>`<br>`--json` |
+| `dataflow <symbol>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | `--full`<br>`--json` |
+| `slice <symbol>` | Reference-level program slice: what affects this (backward) or what this affects (forward) | `--forward`<br>`--depth <n>`<br>`--full`<br>`--json` |
+
+### Cleanup
+
+| Command | Description | Options |
+|---|---|---|
+| `dead [scope]` | Find dead code and file-internal symbols (no cross-file consumers) | `--min-loc <n>`<br>`--include-tests`<br>`--skip-barrels`<br>`--include-members`<br>`--only-dead`<br>`--only-internal`<br>`--full`<br>`--json` |
+| `unused-imports <file>` | Find imports not referenced in the same file | `--full`<br>`--json` |
+| `isolated` | Find completely orphaned symbols (no references at all) | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--full`<br>`--json` |
+| `similar [symbol]` | Find heuristic function similarity candidates from callee fingerprints | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-callees <n>`<br>`--cross-file-only`<br>`--full`<br>`--json` |
+| `similar-files [file]` | Find heuristic similar-file candidates from dependency profiles | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-deps <n>`<br>`--full`<br>`--json` |
+| `react-component-duplicates [file]` | Find heuristic duplicated React component structure candidates from JSX tags, props, events, and bindings | `--min-similarity <n>`<br>`--min-tokens <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
+| `react-hook-candidates [file]` | Find heuristic React hook extraction candidates from shared state, effects, requests, and handlers | `--min-similarity <n>`<br>`--min-shared-behaviors <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
+| `react-large-component-pressure [file]` | Find heuristic large React component pressure candidates from component lines, JSX structure, and hook behavior | `--min-component-lines <n>`<br>`--min-file-lines <n>`<br>`--min-jsx-tokens <n>`<br>`--min-behavior-tokens <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
+| `vue-component-duplicates [file]` | Find heuristic duplicated Vue component structure candidates from template tags, bindings, slots, and directives | `--min-similarity <n>`<br>`--min-tokens <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
+| `vue-composable-candidates [file]` | Find heuristic Vue composable extraction candidates from shared state, effects, requests, and template bindings | `--min-similarity <n>`<br>`--min-shared-behaviors <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
+| `vue-large-view-pressure [file]` | Find heuristic large Vue view pressure candidates from template, script, style, and external script line counts | `--min-total-lines <n>`<br>`--min-template-lines <n>`<br>`--min-script-lines <n>`<br>`--min-style-lines <n>`<br>`--review-thresholds`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
+| `similar-chains` | Find heuristic similar-chain candidates from dependency flows | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-length <n>`<br>`--max-length <n>`<br>`--full`<br>`--json` |
+| `extract-candidates` | Find heuristic extraction candidates from isolated callee clusters | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--min-callees <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+| `locality-candidates [symbol-or-file]` | Find directory-locality and ancestry candidates from consumer ownership | `-s, --scope <path>`<br>`--min-consumers <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+| `cleanup-plan` | Ordered, batched deletion plan: graph-fact dead code plus the cascade candidates it unlocks | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--max-depth <n>`<br>`--verify`<br>`--patch`<br>`--json`<br>`--full` |
+| `cleanup-apply` | Apply a compiler-verified cleanup-plan batch to the working tree | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--max-depth <n>`<br>`--verified`<br>`--batch <n>`<br>`--all`<br>`--force-dirty`<br>`--full` |
+| `recent-duplicates` | Directional duplicate candidates: recent code that re-implements established callable, React, or Vue code | `--window <n>`<br>`--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
+| `doc-drift [doc]` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | `-n, --limit <n>`<br>`--min-coupling <n>`<br>`--full`<br>`--json` |
+| `unused-params` | Speculative-generality candidates: trailing parameters no body ever uses (TS/JS) | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+| `drift [module]` | Detect heuristic drift candidates: unused imports, layer violations, and pattern deviations | `--min-deviation <n>`<br>`--full`<br>`--json` |
+| `wrapper-candidates` | Find heuristic wrapper candidates only called by one consumer | `-s, --scope <path>`<br>`--max-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+| `passthrough-candidates` | Find heuristic passthrough candidates that forward to one callee | `-s, --scope <path>`<br>`--max-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+| `stale-abstractions` | Find heuristic stale abstraction candidates with 0-1 consumers | `-s, --scope <path>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--include-low-confidence`<br>`--full`<br>`--json` |
+| `complexity-hotspots` | Find heuristic complexity hotspot candidates from LOC x fan-in x fan-out | `-s, --scope <path>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+| `convergence <symbol1> <symbol2>` | Show what a consolidated version of two similar functions would look like | `--full`<br>`--json` |
+| `redundant-reexports` | Find barrel re-exports that nobody imports through | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+| `similar-signatures` | Find functions with near-identical type signatures (same shape) | `-s, --scope <path>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+
+### Graph
+
+| Command | Description | Options |
+|---|---|---|
+| `hotspots` | Most-referenced symbols in the codebase (choke points) | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
+| `fan-in [symbol]` | How many files reference a symbol (or top fan-in across codebase) | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
+| `fan-out [file]` | How many external symbols a file uses (or top fan-out across codebase) | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
+| `coupling [file1] [file2]` | Coupling between two files, or top coupled pairs in codebase | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
+| `cycles` | Detect circular dependency chains between files | `-s, --scope <path>`<br>`--max-depth <n>`<br>`--json` |
+| `bottlenecks` | Find coupling hubs: high fan-in AND high fan-out | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-fan-in <n>`<br>`--min-fan-out <n>`<br>`--full`<br>`--json` |
+| `deep-chains` | Find the longest transitive dependency chains | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-depth <n>`<br>`--full`<br>`--json` |
+| `call-graph <symbol>` | Show incoming callers and outgoing callees for a symbol | `--full`<br>`--json` |
+
+### Impact
+
+| Command | Description | Options |
+|---|---|---|
+| `affected <symbol>` | Transitive closure of symbols that could break if this symbol changes | `--max-depth <n>`<br>`-s, --scope <path>`<br>`--json` |
+| `change-surface <file>` | Pre-change briefing: exports, consumers, and blast-radius risk | `--full`<br>`--json` |
+| `co-change [file]` | Files that change together in git history without a dependency edge — hidden coupling candidates | `--min-together <n>`<br>`-n, --limit <n>`<br>`--all`<br>`--full`<br>`--json` |
+| `diff-gate` | Gate the current diff: echo candidates, incomplete migrations, missing co-change partners, uncited doc updates, unused params, new dead symbols; exit 1 on findings | `--base <ref>`<br>`--min-together <n>`<br>`--max-echo-checks <n>`<br>`--max-helpers <n>`<br>`--skip <check>`<br>`--hook`<br>`--json` |
+| `incomplete-migration` | Partially-completed extraction candidates: new helpers in the diff wired into some sites while similar un-migrated sites remain | `--base <ref>`<br>`--min-containment <n>`<br>`--max-helpers <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+| `diff-impact` | Compute changed symbols and downstream consumers from current git diff | `--base <ref>` |
+
+### Planning
+
+| Command | Description | Options |
+|---|---|---|
+| `plan-context <target>` | Pre-edit planning context for a symbol, file, or module | `--impact-depth <n>`<br>`--slice-depth <n>`<br>`-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json` |
+
+### Health
+
+| Command | Description | Options |
+|---|---|---|
+| `self-audit` | Score the cheap evidence paths against the TypeScript compiler oracle on sampled symbols | `--samples <n>`<br>`-s, --scope <path>`<br>`--json` |
+| `health` | Composite codebase health report with prioritized action list | `-s, --scope <path>`<br>`--full`<br>`--json`<br>`--baseline`<br>`--write-baseline` |
+| `complexity <symbol>` | Per-symbol complexity: branches, cyclomatic estimate, fan-in/out, callees | `--full`<br>`--json` |
+
+### Maintenance
+
+| Command | Description | Options |
+|---|---|---|
+| `install-skills` | Install skills (scip-query, scip-query-setup, concrete-plan, scip-ai-cleanup, scip-explore, scip-debloat, scip-doc-reconcile, scip-directory-architecture, scip-maintainability, scip-react-maintainability, scip-vue-maintainability, scip-verify, scip-language-playbook) into Claude Code, Codex, and shared agent roots | - |
+| `check-deps` | Check whether scip-query and the detected language indexers are actually runnable | - |
+| `capabilities` | Report which evidence and verification capabilities are available in this project | `--json` |
+| `capability-matrix` | Report the evidence and verification capability matrix by language | `--json` |
+| `init` | Create a .scipquery.json config file for this project | - |
+| `config-validate` | Validate .scipquery.json, including structured suppressions and declared coupling groups | `--json` |
+| `suppress <id>` | Record an accepted finding in .scipquery.json with a required reason | `--reason <text>`<br>`--check <check>`<br>`--file <path>`<br>`--expires-at <iso>`<br>`--json` |
+| `doctor` | Diagnose config, index freshness, dependency readiness, and project capabilities | `--json` |
+| `setup-agent` | Seed agent guidance for this project: AGENTS.md/CLAUDE.md block pointing agents at the scip-query skills and diff gate, plus an optional git pre-commit backstop | `--git-hook` |
+| `setup-ci` | Write a GitHub Actions workflow that runs scip-query reindex and diff-gate on pull requests | `--force`<br>`--dry-run` |
+| `watch` | Watch for file changes and reindex automatically | `--debounce <ms>`<br>`--cooldown <ms>` |
+| `status` | Show index status for this project | `--json`<br>`--capabilities` |
+
+<!-- END GENERATED COMMAND REFERENCE -->

package/docs/DETECTOR_GUIDE.md

@@ -0,0 +1,119 @@
+# Which Detector Do I Want?
+
+scip-query has several detectors that sound alike but answer different
+questions. This guide explains what each one actually measures, the
+differences inside each confusable cluster, and which check to run after which
+kind of change. (The companion doc [AI_FAILURE_MODES.md](AI_FAILURE_MODES.md)
+maps these to the agent behaviors that create the problems.)
+
+---
+
+## Cluster 1 — "This structure shouldn't exist" (the speculation family)
+
+Same disease — structure built for a future that never came — detected at
+four different altitudes:
+
+| Command | Altitude | What it measures | The fix |
+|---|---|---|---|
+| `unused-params` | **parameter** | Trailing parameters no body ever uses. TS/JS only, trailing-run only — removals that are type-safe by construction. `_`-prefixed and externally-published signatures are exempt. | Delete the parameters and their call-site arguments. |
+| `passthrough-candidates` | **function (fan-out view)** | Functions with exactly **one callee** and a small body — they just forward arguments to the real implementation. | Inline it: call the target directly. |
+| `wrapper-candidates` | **function (fan-in view)** | Symbols with exactly **one caller** — indirection that provides no reuse. Strongest when the sole caller is itself widely used. | Fold the body into the caller. |
+| `stale-abstractions` | **type** | Classes, interfaces, and type aliases with 0–1 *real* cross-file consumers (barrel re-exports don't count as consumers). Single-implementation interfaces, misplaced types. | De-abstract: replace the interface with the concrete thing, or move the type to its one consumer. |
+
+How to keep them straight:
+
+- `passthrough` looks **down** (what does this function call? one thing) —
+  `wrapper` looks **up** (who calls this function? one caller). A function can
+  be both: a one-line forwarder with a single caller is the purest bloat.
+- `unused-params` is *inside* a signature; the other three are *about whole
+  symbols*.
+- `stale-abstractions` is the only one about **types**, not behavior. Note its
+  confidence ranking: a single-consumer `class` is usually deliberate
+  encapsulation (low), a single-consumer `interface` is worth questioning
+  (medium), a zero-consumer type is just dead (high).
+
+## Cluster 2 — "This already exists" (the similarity family)
+
+All of these find duplication, but at different granularities and with
+different evidence — and two of them add *direction*:
+
+| Command | Granularity | Evidence | Question it answers |
+|---|---|---|---|
+| `similar <symbol>` | function | callee-fingerprint cosine (TF-IDF), source-token fallback | "What else does roughly what this function does?" |
+| `similar-signatures` | function | normalized parameter + return types | "What has the same *shape*, regardless of body?" |
+| `similar-files` | file | Jaccard on import/dependency profiles | "Which files are copy-paste variants of each other?" |
+| `similar-chains` | pipeline | edit distance on infrastructure-filtered dependency chains | "Which end-to-end flows are parallel re-implementations?" |
+| `recent-duplicates` | callable/frontend unit + **git age** | callable, React, and Vue similarity + file-add history | "Which side is the established original, which is the fresh echo?" (ECHO = new copies old; TWIN = both new) |
+| `incomplete-migration` | function + **git diff** | callee *containment* vs new-in-diff helpers | "I just extracted a helper — which call sites still have the logic inline and were never migrated?" |
+| `convergence <a> <b>` | a known pair | shared/unique callees | "I already know these two overlap — give me the merge prescription." |
+
+How to keep them straight:
+
+- Use `similar` when you have **one symbol** in hand; `similar-files` /
+  `similar-chains` for repo-wide sweeps at coarser grain;
+  `similar-signatures` when implementations differ but the shape repeats.
+- `recent-duplicates` is duplicate evidence **plus direction in time** - it tells you
+  which copy to delete. Run it after agent sessions. It covers generic callables,
+  React component structure, React hook behavior, Vue template structure, and
+  Vue composable-like behavior.
+- `incomplete-migration` is the **inverse of an echo**: the *new* code is the
+  canonical one (the helper you just extracted), and the *established* code is
+  what should disappear. It also scores by containment, not symmetric
+  similarity, because an un-migrated site holds the helper's logic *plus* its
+  own — cosine under-scores exactly those.
+- `extract-candidates` is the **before** picture: seams inside one big
+  function that *should* become a helper. `incomplete-migration` is the
+  **after** picture: you made the helper but didn't finish moving everyone
+  onto it.
+
+## Cluster 3 — "Things drifting apart" (the drift family)
+
+Three detectors share the word "drift" or the concept; they watch different
+gaps:
+
+| Command | Watches the gap between | Evidence |
+|---|---|---|
+| `drift` | a file and its **siblings/architecture** | reference graph: unused imports, layer violations, "no sibling imports this" deviations |
+| `doc-drift` | **docs** and the code they describe | doc file-citations + doc↔code co-change history; flags broken references and staleness scores |
+| `co-change` | two **files** with an invisible contract | git history: pairs that change together with no dependency edge |
+
+How to keep them straight: `drift` is structural and intra-code, `doc-drift`
+is prose-vs-code, `co-change` is code-vs-code where the connection exists only
+in commit history. The diff-gate runs all three angles scoped to your change
+(`doc-reference` and `co-change-partner` checks).
+
+## Cluster 4 — "Nothing uses this" (the deadness family)
+
+| Command | Scope | Question |
+|---|---|---|
+| `dead` | symbols | "What has zero consumers?" (evidence-ranked, entrypoint-aware) |
+| `isolated` | callables | "What is fully disconnected — no callers *and* no callees?" |
+| `cleanup-plan` | the cascade | "If I delete the dead stuff, what *becomes* dead next — and will my compiler vouch for the whole batch?" (`--verify`) |
+
+`dead` finds candidates; `isolated` finds the most extreme subset;
+`cleanup-plan --verify` turns candidates into a compiler-proven deletion plan.
+Don't hand-delete from `dead` output when `cleanup-plan` can prove it.
+
+---
+
+## After-the-change check matrix
+
+The reflex to build (and the one the `scip-query` router skill teaches
+agents): match the check to what the change *did*. `diff-gate` runs the
+broad sweep on every diff; these are the targeted follow-ups.
+
+| You just... | Run |
+|---|---|
+| Extracted a helper / created an abstraction | `scip-query incomplete-migration` — did every site migrate? |
+| Wrote a brand-new helper or module | `scip-query similar <it>` and `scip-query recent-duplicates` — did it already exist? |
+| Added parameters, options, or config flags | `scip-query unused-params` — does anything use them yet? |
+| Added a forwarding/wrapper layer | `scip-query wrapper-candidates` and `scip-query passthrough-candidates` — does it earn its indirection? |
+| Added an interface, base class, or type alias | `scip-query stale-abstractions` — does it have more than one real consumer? |
+| Changed a schema, contract, config, or generated file | `scip-query co-change <file>` — who historically moves with it? |
+| Changed code that docs describe | `scip-query doc-drift` — which docs now lie? |
+| Deleted code | `scip-query cleanup-plan --verify` — what else just became dead, and does the compiler agree? |
+| Anything at all, before saying "done" | `scip-query reindex && scip-query diff-gate` |
+
+And before any non-trivial change: plan with `scip-query plan-context
+<target>` (or the `concrete-plan` skill, which requires a scip-query citation
+for every claim in the plan).

package/docs/accuracy-hardening-goal.md

@@ -0,0 +1,54 @@
+# Accuracy Hardening Goal
+
+Make scip-query's command answers reliable across languages and repositories by separating smoke tests from source-backed accuracy checks, fixing lookup/call-graph gaps found by real repos, and labeling heuristic results as candidates rather than exact facts.
+
+## Scope
+
+- Keep CI changes out of scope for now.
+- Add committed test coverage that runs locally with `npm test`.
+- Keep real-repo calibration optional because those repositories exist only on some machines.
+- Prefer fixes that improve the shared indexing/query machinery over tuning output for one repository.
+
+## Deliverables
+
+1. Source-backed command accuracy coverage:
+   - Add fixture/oracle tests for exact commands such as `symbols`, `code`, `refs`, `trace`, `call-graph`, `complexity`, `dataflow`, and `slice`.
+   - Cover TypeScript, Python, Rust, and mixed-index behavior where practical.
+   - Assert against source facts: definition text, expected files, expected callees/callers, and line-bounded code snippets.
+
+2. Optional real-repo calibration harness:
+   - Add a script that can run against local repositories when they exist.
+   - Reindex each repo into a temporary cache.
+   - Run source-backed checks for selected known symbols.
+   - Print clear PASS/FAIL output with the command and evidence.
+   - Never require these private/local repositories in normal test runs.
+
+3. Indexer reliability taxonomy:
+   - Preserve the existing fail-closed behavior for failed languages.
+   - Keep `--allow-partial` as the explicit opt-in for incomplete mixed-language indexes.
+   - Repair malformed SCIP definition occurrences before SQLite conversion when that can be done without inventing symbol metadata.
+   - Keep conversion failures actionable and specific.
+
+4. Lookup and call-graph accuracy:
+   - Fix path-qualified lookup ranking such as `src/app.rs/run` so it prefers symbols defined in that file.
+   - Keep exact call graph facts precise while still recovering real callable edges from SCIP mentions when AST extraction misses them.
+   - Add regression tests for Rust qualified path calls.
+
+5. Heuristic output labeling:
+   - Label heuristic commands as candidates in CLI output.
+   - Make the distinction visible for `similar`, `similar-files`, `similar-chains`, `extract-candidates`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `complexity-hotspots`, and `drift`.
+   - Avoid implying those commands are exact compiler facts.
+
+6. Performance guardrails:
+   - Add an optional local performance/calibration path that records durations and index sizes.
+   - Do not fail normal tests on private-repo timing.
+
+## Acceptance Criteria
+
+- `npm test` passes.
+- `npm run typecheck` passes.
+- `npm run build` passes.
+- The optional calibration script passes on at least one TypeScript repo, one Python repo, and one Rust repo when those repos exist locally.
+- Path-qualified Rust lookup resolves `src/app.rs/run` to `app:run()`, not an unrelated `run`-named test.
+- `call-graph main` in the Rust fixture reports the qualified `app:run()` callee.
+- Heuristic command output includes explicit candidate/disclaimer language.

package/docs/analyzer-inventory.md

@@ -0,0 +1,162 @@
+# Analyzer Inventory and Action-Tier Review
+
+An analyzer in this project is a query or command-backed program that examines repository evidence such as the SCIP graph, source text, AST profiles, git history, docs, or a diff, and returns a structured answer about code health, change risk, reuse, or navigation.
+
+A finding is an analyzer result that names a concrete codebase location, relationship, or diff condition as worth attention. Its defining role is to turn raw evidence into a maintainer-facing claim.
+
+The useful product split is not the same as evidence quality. Evidence quality says how the claim was obtained: graph fact, semantic provider, source heuristic, change graph, or baseline. Action tier says how strongly the claim justifies a repair without broader product or architecture judgment.
+
+Companion docs:
+
+- `docs/analyzer-validation-protocol.md` defines how to validate true positives, false positives, and false negatives across real repositories.
+- `docs/analyzer-validation-ledger.md` tracks the remaining validation work, run batches, and completion state.
+- `docs/locality-analyzer-design.md` designs the missing code-organization analyzer for extraction placement and shared-folder locality.
+
+The action tiers are:
+
+- Direct repair evidence identifies code or docs that usually need a local action: delete, wire up, finish migration, remove unused surface, break a cycle, or split excessive complexity. Review is still required, but the default next step is action.
+- Contextual signal evidence identifies a pattern that may hide a better design, but the right action depends on ownership, product semantics, locality, naming, or architecture. The default next step is investigation.
+- Support analysis provides facts used by people, agents, or other analyzers, but does not itself assert a smell.
+
+## Current Surfaces
+
+The published query surface lives in `src/queries/public-query-entries.ts`. The CLI command order and families live in `src/runtime/commands/query-command-specs.ts`. The composite health score runs the phases listed in `HEALTH_PHASES` in `src/queries/health/health.ts`. The diff gate runs the checks listed in `DIFF_GATE_CHECKS` in `src/queries/impact/diff-gate.ts`.
+
+`health --json` on this repository currently reports:
+
+- score 100, riskScore 100, hygieneScore 100
+- zero active findings across all health phases
+- 174 suppression comments: 72 extract, 62 wrapper, 17 stale, 15 similar, 8 passthrough
+
+That suppression shape is evidence that broad candidate analyzers have historically produced enough accepted or false-positive results to need explicit maintainer judgment. The suppression lifecycle review confirmed the current source comments are recent and reasoned, while structured file-scoped suppressions now warn when their file path goes stale.
+
+The declared-coupling config has been refreshed after the inventory surfaced old pre-folder-move paths. `config-validate` now warns when a declared-coupling entry names a file that no longer exists, so known maintenance units stay connected to the current file graph instead of silently becoming stale metadata.
+
+## Health-Scored Analyzers
+
+| Analyzer                         | Evidence examined                                                                                                                                                                                                   |                 Current health role | Recommended action tier                                                                              | Evaluation                                                                                                                                                                                                                                                                                                      |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------: | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dead`                           | Production definitions, SCIP/source/caller references, package roots, framework-discovered route/page roots, and entry exclusions                                                                                   |                Risk, graph findings | Direct repair for `dead-code`; contextual for `file-internal`                                        | Strong when `kind === dead-code`: zero references and excluded external-live surfaces make deletion likely. `file-internal` is not direct deletion evidence; it may be private helper ownership.                                                                                                                |
+| `cleanup-plan`                   | `dead --only-dead` seed plus conservative cascade references                                                                                                                                                        | Standalone, not direct health phase | Direct repair                                                                                        | Strongest deletion analyzer. It computes ordered batches and can be compiler-verified from the command layer.                                                                                                                                                                                                   |
+| `isolated`                       | Production callables with no callers and no non-self callees                                                                                                                                                        |                Risk, graph findings | Direct repair                                                                                        | Strong dead-leaf signal. It is stricter than `dead` and usually means remove or wire up.                                                                                                                                                                                                                        |
+| `cycles`                         | File dependency graph, with module-hierarchy/test/barrel/entry cycle classification                                                                                                                                 |                                Risk | Direct repair for `real`; support/noise for `module-hierarchy`                                       | Good split already exists. Real cycles normally need architectural repair. Module-hierarchy cycles should not score.                                                                                                                                                                                            |
+| `similar` / `similarAll`         | Callable callee fingerprints, IDF weighting, source-token fallback                                                                                                                                                  |                             Hygiene | Contextual signal                                                                                    | Similarity is a reuse lead, not proof of duplicate semantics. Needs naming, behavior, signatures, and product intent before action. Shared evidence is now labeled as domain, access/query, framework/generic, mixed, or neutral structural overlap.                                                            |
+| `recent-duplicates`              | `similarAll`, React/Vue duplicate analyzers, git file-age orientation                                                                                                                                               |                  Standalone cleanup | Direct repair for `echo`; contextual for `twin`                                                      | Directionality makes this much stronger than plain similarity. A recent echo usually should reuse/delete. Twins still need choice of owner.                                                                                                                                                                     |
+| `react-component-duplicates`     | JSX structure tokens from React profiles                                                                                                                                                                            |                             Hygiene | Contextual signal                                                                                    | Good UI reuse lead. Needs product semantics and design-system judgment before extracting.                                                                                                                                                                                                                       |
+| `react-hook-candidates`          | Shared React hook/state/effect/request/handler tokens, evidence class, action tier, and recommendation                                                                                                              | Hygiene, with `scoreCount` discount | Contextual signal for domain or mixed behavior; support for generic workflow/shared abstraction rows | Better than raw similarity because behavior tokens are named. The output now separates generic UI workflow and existing shared abstractions from domain behavior, but extraction still needs product judgment.                                                                                                  |
+| `react-large-component-pressure` | Component LOC, file LOC, JSX token count, behavior token count, pressure kind, context, recommendation kind                                                                                                         |                             Hygiene | Direct repair pressure with review direction                                                         | Large component pressure usually implies splitting. It now distinguishes JSX, behavior, file, and route/page pressure, but still does not choose the destination directory for extracted code.                                                                                                                  |
+| `vue-component-duplicates`       | Vue template structure tokens                                                                                                                                                                                       |                             Hygiene | Contextual signal                                                                                    | Same reuse caveat as React component duplicates.                                                                                                                                                                                                                                                                |
+| `vue-composable-candidates`      | Vue composable/store/reactivity/lifecycle/request/function/template tokens, evidence class, action tier, and recommendation                                                                                         | Hygiene, with `scoreCount` discount | Contextual signal for domain or mixed behavior; support for generic workflow/shared abstraction rows | Good extraction lead when domain behavior is present. Generic workflow scaffolding remains visible as support, and extraction still needs domain and locality judgment.                                                                                                                                         |
+| `vue-large-view-pressure`        | SFC total/template/script/style/external-script line counts, pressure kind, context, recommendation kind                                                                                                            |                             Hygiene | Direct repair pressure with review direction                                                         | Usually implies splitting a large view. It now distinguishes template, script, style, external-script, and route/page pressure, but still needs companion directory-locality guidance.                                                                                                                          |
+| `extract-candidates`             | Large callable callee clusters, co-occurrence isolation, extraction kind, action tier, and recommendation                                                                                                           |                             Hygiene | Contextual signal                                                                                    | It finds possible extraction seams, not proof of a new abstraction. The output now distinguishes workflow orchestration from broad/cohesive helper clusters and keeps every row as signal.                                                                                                                      |
+| `wrapper-candidates`             | Small production callables with one real external caller, caller fan-in, and boundary-token evidence                                                                                                                |                             Hygiene | Contextual signal, sometimes direct                                                                  | Single-caller wrappers can be needless indirection, but may also be names, domain/lifecycle boundaries, test seams, or API shaping. Boundary evidence discounts those without hiding them.                                                                                                                      |
+| `passthrough-candidates`         | Small production callables with exactly one callee, literal pass-through body, runtime-boundary evidence, public-facade evidence, action tier, recommendation, and score count                                      | Hygiene, with `scoreCount` discount | Direct when no boundary or public-facade evidence is present; contextual signal when either exists   | Body-shape gate is real. Boundary evidence distinguishes adapter, provider, public, capability, transport, lifecycle, access-policy, and facade-shaped forwarders; public-facade evidence separately identifies package-public or rooted exported passthroughs.                                                 |
+| `stale-abstractions`             | Type-like definitions, real consumers, barrel consumers, transitive reachability, definer usage, confidence, staleness kind, action tier, and recommendation                                                        |                             Hygiene | Direct for unused abstractions; contextual signal for one-consumer ownership rows                    | `0 consumers` is direct repair. `1 consumer` is contextual, including high-confidence misplaced types, because the repair may be move, inline, keep, or document as public contract.                                                                                                                            |
+| `drift`                          | File dep graph, symbol ref graph, semantic/source import usage, explicit or inferred layer policy, sibling patterns, action tier, policy basis, recommendation                                                      |                             Hygiene | Split by kind                                                                                        | `unused-import` is direct repair. Explicit `layer-violation` is direct; inferred layer policy and `pattern-deviation` rows are contextual signal. Pattern deviations remain excluded from health scoring.                                                                                                       |
+| `complexity-hotspots`            | Production callable LOC, fan-in, fan-out, callee count                                                                                                                                                              |                                Risk | Direct repair pressure                                                                               | Complexity pressure usually means refactor, but the current score is structural, not cyclomatic. It should be separate from branch-count complexity.                                                                                                                                                            |
+| `co-change` / hidden coupling    | Git co-change pairs, dependency edges, declared couplings, file noise filters, partner-class labels, declared-coupling suggestions, commit scope, recency context, commit-subject context, and score-weighted count |  Risk, weighted by history strength | Contextual signal                                                                                    | Strong evidence that coordination may be missing, but not proof that extraction or unification is correct. Partner classes, history context, subject context, and score weighting now separate contract-like focused current pairs from broad, stale, or unlabeled history before suggesting declared coupling. |
+| Suppression inventory            | `scip-query: ignore-*` comments in source, plus structured `.scipquery.json` suppressions                                                                                                                           |               Evidence quality axis | Meta signal                                                                                          | Useful precision feedback. High suppressions should reduce trust or weight for that detector family. Structured file-scoped suppressions now validate path freshness.                                                                                                                                           |
+
+## Diff-Gate Checks
+
+| Check                  | Evidence examined                                                                                                                                                                         | Recommended action tier    | Evaluation                                                                                                                                                                                                                                                                                                    |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `echo`                 | Changed symbols compared to established `similar` matches outside the diff                                                                                                                | Direct repair leaning      | More actionable than repo-wide `similar` because it is scoped to new or changed code. Still verify semantics before reuse.                                                                                                                                                                                    |
+| `incomplete-migration` | New helpers in the diff, existing references, leftover established sites with helper-callee containment, site coverage, helper-shape evidence, and migration-scope hints                  | Direct repair              | Strong. It models the exact failure mode of half-finished extraction and gives concrete leftover sites, while rejecting broad old sites where the helper pattern is only a small fragment and labeling possible subtype/variant leftovers for review.                                                         |
+| `co-change-partner`    | Historical partner changed without the other side in current diff, with co-change partner class, commit scope, recency, commit-subject context, and optional declared-coupling suggestion | Contextual signal          | Good sync warning, but sometimes the coupling no longer holds or should be intentionally broken. Partner classes, history context, and subject context make doc/code, config/code, schema/script, model/view, test/code, broad-sweep, stale, docs-labeled, fix-labeled, and issue-ref cases easier to review. |
+| `doc-reference`        | Living docs citing changed files, excluding import-only source changes, with citation kind and Markdown-local cited-claim context                                                         | Split by citation evidence | Behavioral/current doc claims are direct doc-review evidence. Configuration examples and intentional records are support-tier checks unless the cited target changed meaning.                                                                                                                                 |
+| `unused-params`        | Trailing unused params in changed files                                                                                                                                                   | Direct repair              | Conservative enough to be a high-confidence local fix.                                                                                                                                                                                                                                                        |
+| `new-dead`             | Changed production symbols with zero consumers, excluding entry/root/test/framework-discovered cases                                                                                      | Direct repair              | Either wire it up, remove it, or mark it as an externally live root before it lands.                                                                                                                                                                                                                          |
+| `baseline`             | New health finding identity versus committed baseline                                                                                                                                     | Direct gate                | It does not explain the smell itself, but correctly blocks regression until fixed or accepted.                                                                                                                                                                                                                |
+
+## Standalone Cleanup and Similarity Analyzers
+
+| Analyzer              | Evidence examined                                                                                                                              | Recommended action tier                                       | Evaluation                                                                                                                                                                                    |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `unused-params`       | TS/JS AST facts plus identifier usage lines                                                                                                    | Direct repair                                                 | Intentionally conservative: trailing only, simple params only, underscore-intent skipped, external roots skipped. Should be in the direct tier despite heuristic metadata.                    |
+| `unused-imports`      | Source/AST import facts plus local binding usage                                                                                               | Direct repair                                                 | A narrower direct cleanup analyzer. It should stay direct when the imported binding is unused in executable and type surfaces, with framework/compiler caveats handled in `drift` validation. |
+| `redundant-reexports` | Barrel exports, JS/TS re-export statements, SCIP/source fallback consumers, direct importers, package-surface evidence                         | Direct for private barrels; signal for package-public barrels | Strong when the candidate barrel is private and both barrel and direct consumers are zero. Package-public barrels stay visible as signal because external consumers may import through them.  |
+| `similar-files`       | File dependency-profile Jaccard with infrastructure and distinctive-dep gates                                                                  | Contextual signal                                             | Good for copy-paste family discovery, not direct extraction proof.                                                                                                                            |
+| `similar-chains`      | Dependency chain generation, infrastructure filtering, edit distance                                                                           | Contextual signal                                             | Finds duplicated pipelines, but pipeline ownership and abstraction shape require design judgment.                                                                                             |
+| `similar-signatures`  | Semantic/documented/source normalized function signatures                                                                                      | Contextual signal                                             | Same type shape is only a weak lead. Useful for search, not scoring unless combined with behavior evidence.                                                                                   |
+| `convergence`         | Two symbols' shared and unique callees                                                                                                         | Support/contextual signal                                     | It explains a possible consolidation strategy; it should not score by itself.                                                                                                                 |
+| `locality-candidates` | Candidate symbol/file path, directory ancestry, consumer files, consumer coverage, nearest common owner, boundary markers, and counterevidence | Contextual signal                                             | Guides placement and ownership review for extracted or shared code. It is deliberately report-only and should not force moves or affect health score without repair-outcome evidence.         |
+| `doc-drift`           | Living docs, path citations, cited-claim contexts, doc-code co-change, doc intent, action tier, code churn after doc update, broken references | Split by evidence                                             | Broken references are direct repair. Path-cited stale subjects now expose citation context. Co-change-only staleness is signal for current guidance and support for historical notes.         |
+
+## Graph, Risk, and Planning Analyzers
+
+| Analyzer             | Evidence examined                                                                                                                  | Recommended role          | Evaluation                                                                                                                                                          |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `affected`           | Transitive symbol impact from a changed symbol                                                                                     | Support analysis          | Blast-radius map, not smell.                                                                                                                                        |
+| `change-surface`     | Definitions in a file plus external consumer counts                                                                                | Support/risk analysis     | Pre-change risk briefing. Useful for planning and score context, not a repair.                                                                                      |
+| `plan-context`       | Trace, references, call graph, dataflow, deps/rdeps, surface, affected, change-surface, complexity, history                        | Support analysis          | Composite planning bundle. It should not contribute smell score directly.                                                                                           |
+| `bottlenecks`        | Callable fan-in times fan-out, risk kind, action tier, evidence reasons, recommendation                                            | Contextual signal         | Good risk hotspot, not automatic refactor. Output now states `signal` and frames central code as coordination risk rather than repair proof.                        |
+| `hotspots`           | Most referenced symbols                                                                                                            | Support/contextual signal | Identifies choke points. Not a smell alone.                                                                                                                         |
+| `fan-in` / `fan-out` | Reference counts into symbols or out of files                                                                                      | Support analysis          | Raw graph metrics.                                                                                                                                                  |
+| `coupling`           | Shared symbols between two files or top coupled pairs, coupling kind, action tier, evidence reasons, recommendation                | Contextual signal         | May reveal boundary problems, but shared symbols can be intended. Output now makes the coordination-pressure interpretation explicit.                               |
+| `deep-chains`        | Longest dependency chains after SCC condensation, suffix de-duplication, chain kind, action tier, evidence reasons, recommendation | Contextual signal         | Long chains imply propagation risk, but action depends on layers and ownership. Strict suffix duplicates are now removed from top results.                          |
+| `complexity`         | Branch count, cyclomatic estimate, callee count, fan-in, fan-out for one symbol                                                    | Direct repair pressure    | This is closer to the user-specified "cyclomatic complexity" analyzer than `complexity-hotspots`. Should score strongly when branches/cyclomatic exceed thresholds. |
+| `self-audit`         | Cheap evidence paths checked against TypeScript compiler oracle                                                                    | Meta analysis             | Measures analyzer accuracy. Should guide trust/weight, not code health directly.                                                                                    |
+
+## Navigation and Evidence Providers
+
+These commands analyze the index, but they are not finding detectors and should not affect health score directly: `stats`, `files`, `methods`, `refs`, `trace`, `deps`, `rdeps`, `system`, `surface`, `imports`, `imported-by`, `outline`, `members`, `by-kind`, `kind-counts`, `hierarchy`, `call-graph`, `code`, `dataflow`, and `slice`.
+
+They are essential because other analyzers and agents use them to ground claims. Their defining characteristic is retrieval or explanation, not smell detection.
+
+The support-analysis accuracy review confirmed that `refs`, `affected`, `change-surface`, `plan-context`, `imports`, `deps`, `rdeps`, `fan-in`, `fan-out`, `hotspots`, `status`, and `self-audit` return useful source-grounded evidence for a TypeScript target. It also fixed diagnostic parity so `status` and `doctor` use the same root-aware config validation as `config-validate`.
+
+The cross-language boundary review confirmed that Rust projects have graph-backed indexing, source fallback, cleanup detector output, git/diff support, and compiler cleanup verification when `rust-analyzer` and `cargo check` are available. It also confirmed that TypeScript semantic self-audit is explicitly unavailable on Rust and that React/Vue analyzers return stack-specific empty results rather than Rust findings.
+
+`cleanup-apply` is not an analyzer. It is an action command that applies a `cleanup-plan` batch, so it should be validated through the `cleanup-plan --verify` path and normal project checks.
+
+## Overlap and Duplication Review
+
+The codebase already avoids some duplicate analysis by sharing kernels:
+
+- `runCandidateAnalysis` gives candidate-style analyzers one lifecycle for scan limits, preparation, evaluation, ordering, and result caps.
+- `rankedPairwiseProfileResults` gives React, Vue, file-profile, and pairwise similarity analyzers a shared pair-ranking shape.
+- `HEALTH_DETECTOR_PROFILES` keeps health and baseline detector options aligned.
+
+The remaining conceptual overlap is mostly healthy, but needs product labels:
+
+| Overlap family             | Members                                                                                                                              | Same analysis or distinct?                                                                                      | Recommendation                                                                                                                                          |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Deletability               | `dead`, `isolated`, `cleanup-plan`, `redundant-reexports`, `new-dead`                                                                | Distinct evidence scopes over the same core question: can this be removed or must it be wired?                  | Model as one "deletability" action family with subtypes and confidence.                                                                                 |
+| Similarity and reuse       | `similar`, `similar-files`, `similar-chains`, `similar-signatures`, `convergence`, React/Vue duplicates, `recent-duplicates`, `echo` | Distinct evidence bases. The risk is UX confusion, not implementation duplication.                              | Keep separate, but expose basis, action tier, and root-cause groups where pairwise rows repeat.                                                         |
+| Extraction pressure        | `extract-candidates`, React/Vue behavior candidates, large component/view pressure, `incomplete-migration`                           | Different stages: discover seam, detect duplicated behavior, detect excessive size, catch unfinished migration. | Score unfinished migrations higher than discovery leads.                                                                                                |
+| Indirection                | `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`                                                                 | Related but not the same: single caller, literal forwarding, low-consumer types.                                | Passthrough and wrapper rows now split by boundary evidence; stale should split by confidence.                                                          |
+| Architecture/history drift | `drift`, `doc-drift`, `co-change`, `co-change-partner`, `doc-reference`                                                              | Same broad problem of things moving out of sync, but sources differ.                                            | Co-change should remain signal; doc-reference is direct only for behavioral cited claims and support for configuration examples or intentional records. |
+| Graph risk                 | `fan-in`, `fan-out`, `hotspots`, `bottlenecks`, `coupling`, `deep-chains`, `change-surface`, `affected`                              | Mostly layered views of graph pressure.                                                                         | Treat as support/context, except `cycles` and high cyclomatic complexity.                                                                               |
+
+## Score Model Implications
+
+The current report has `riskScore`, `hygieneScore`, evidence labels, `scoreCount`, pressure penalties, validation lift, and suppression inventory. That is close, but it does not encode action implication directly.
+
+Recommended model:
+
+1. Add an action tier to each finding category: `direct`, `signal`, or `support`.
+2. Keep evidence quality separate: `graph-fact`, `semantic`, `heuristic`, `change-graph`, `baseline`.
+3. Score direct findings with heavier base penalties because they usually imply a local repair.
+4. Score signal findings with lighter base penalties and stronger pressure penalties when signals accumulate.
+5. Add a "signal backlog pressure" multiplier when direct findings are near zero but contextual signals remain high. This captures the user's point: a repo with no obvious smells but many unresolved architectural signals is not actually clean.
+6. Let suppression history and `self-audit` validation adjust detector trust. A detector with many suppressions or low validation lift should score less until recalibrated.
+
+Suggested initial tier map:
+
+- Direct: `cleanup-plan`, `dead-code`, `isolated`, `real cycles`, `unused-params`, `new-dead`, `incomplete-migration`, behavioral/current `doc-reference` claims, broken `doc-drift` references, `redundant-reexports` with zero consumers, direct passthrough rows with no boundary or public-facade role, `unused-import` drift, high branch/cyclomatic `complexity`, large React/Vue pressure.
+- Signal: `co-change`, `co-change-partner`, ordinary `similar`, `similar-files`, `similar-chains`, `similar-signatures`, `convergence`, `extract-candidates`, `locality-candidates`, `wrapper-candidates`, `passthrough-candidates` with boundary or public-facade roles, single-consumer `stale-abstractions`, React/Vue duplicate or behavior candidates, bottlenecks, hotspots, coupling, deep chains, inferred layer or pattern drift, doc staleness from churn.
+- Support: navigation commands, `affected`, `change-surface`, `plan-context`, `stats`, `self-audit`, suppression inventory, baseline comparison mechanics, configuration-example and intentional-record `doc-reference` rows.
+
+## Directory Locality Analyzer
+
+`locality-candidates` now evaluates extraction locality after a large component/view or helper extraction. The referents are directories, feature folders, local shared folders, global shared folders, import distances, consumer sets, and abstraction ownership. The analyzer classifies where an extracted unit may belong by comparing actual consumers and directory boundaries.
+
+Command shape:
+
+- `scip-query locality-candidates [symbol-or-file]`
+- Inputs: extracted or candidate symbol/file, consumer files, nearest common ancestor, feature/domain folders, existing shared folders, import path depth, package/workspace boundaries, and whether consumers cross feature boundaries.
+- Outputs: recommended locality level such as same file, sibling folder, feature-local shared folder, app-level shared folder, package-level shared module, or no extraction.
+- Action tier: contextual signal. It guides placement; it should not force moves without architecture judgment.
+
+This should pair with `react-large-component-pressure`, `vue-large-view-pressure`, `extract-candidates`, and `incomplete-migration` so agents do not reduce size scores by dumping extracted pieces into flat local directories.