scip-query 0.9.0 → 0.10.1

package/docs/COMMAND_REFERENCE.md

@@ -0,0 +1,130 @@
+# 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>`-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` |
+| `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, concrete-plan, scip-ai-cleanup, scip-explore, scip-debloat, scip-doc-reconcile, 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/assets/scip-query-logo-dark.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="560" height="136" viewBox="0 0 560 136" role="img" aria-labelledby="title desc">
+  <title id="title">scip-query</title>
+  <desc id="desc">A minimal scip-query wordmark with a bright blue underscore cursor for dark backgrounds.</desc>
+  <style>
+    .wordmark {
+      fill: #F8FAFC;
+      font-family: Helvetica, Arial, sans-serif;
+      font-size: 58px;
+      font-weight: 700;
+      letter-spacing: 0;
+    }
+  </style>
+  <text
+    class="wordmark"
+    x="38"
+    y="83"
+    textLength="372"
+    lengthAdjust="spacingAndGlyphs"
+  >scip-query</text>
+  <rect x="430" y="76" width="50" height="8" rx="4" fill="#60A5FA" />
+</svg>

package/docs/assets/scip-query-logo.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="560" height="136" viewBox="0 0 560 136" role="img" aria-labelledby="title desc">
+  <title id="title">scip-query</title>
+  <desc id="desc">A minimal scip-query wordmark with a blue underscore cursor.</desc>
+  <style>
+    .wordmark {
+      fill: #111827;
+      font-family: Helvetica, Arial, sans-serif;
+      font-size: 58px;
+      font-weight: 700;
+      letter-spacing: 0;
+    }
+    .cursor {
+      fill: #2563EB;
+    }
+  </style>
+  <text
+    class="wordmark"
+    x="38"
+    y="83"
+    textLength="372"
+    lengthAdjust="spacingAndGlyphs"
+  >scip-query</text>
+  <rect class="cursor" x="430" y="76" width="50" height="8" rx="4" />
+</svg>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "scip-query",
-  "version": "0.9.0",
-  "description": "Language-agnostic code intelligence CLI powered by SCIP indexes",
+  "version": "0.10.1",
+  "description": "Evidence and verification for AI coding agents: map code, reuse concepts, finish migrations, and gate diffs.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,6 +11,8 @@
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
+    "docs/assets/**/*",
+    "docs/*.md",
     "skills/**/SKILL.md"
   ],
   "sideEffects": false,
@@ -195,6 +197,30 @@
       "import": "./dist/queries/similar-files.js",
       "types": "./dist/queries/similar-files.d.ts"
     },
+    "./queries/react-component-duplicates": {
+      "import": "./dist/queries/react-component-duplicates.js",
+      "types": "./dist/queries/react-component-duplicates.d.ts"
+    },
+    "./queries/react-hook-candidates": {
+      "import": "./dist/queries/react-hook-candidates.js",
+      "types": "./dist/queries/react-hook-candidates.d.ts"
+    },
+    "./queries/react-large-component-pressure": {
+      "import": "./dist/queries/react-large-component-pressure.js",
+      "types": "./dist/queries/react-large-component-pressure.d.ts"
+    },
+    "./queries/vue-component-duplicates": {
+      "import": "./dist/queries/vue-component-duplicates.js",
+      "types": "./dist/queries/vue-component-duplicates.d.ts"
+    },
+    "./queries/vue-composable-candidates": {
+      "import": "./dist/queries/vue-composable-candidates.js",
+      "types": "./dist/queries/vue-composable-candidates.d.ts"
+    },
+    "./queries/vue-large-view-pressure": {
+      "import": "./dist/queries/vue-large-view-pressure.js",
+      "types": "./dist/queries/vue-large-view-pressure.d.ts"
+    },
     "./queries/similar-signatures": {
       "import": "./dist/queries/similar-signatures.js",
       "types": "./dist/queries/similar-signatures.d.ts"
@@ -245,7 +271,7 @@
     }
   },
   "scripts": {
-    "build": "tsup",
+    "build": "node --max-old-space-size=8192 ./node_modules/tsup/dist/cli-default.js",
     "dev": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -280,6 +306,8 @@
   "dependencies": {
     "@bufbuild/protobuf": "^2.11.0",
     "@c4312/scip": "^0.1.0",
+    "@vue/compiler-dom": "^3.5.38",
+    "@vue/compiler-sfc": "^3.5.38",
     "better-sqlite3": "^12.9.0",
     "commander": "^13.1.0",
     "ignore": "^7.0.3",

package/skills/scip-maintainability/SKILL.md

@@ -1,8 +1,7 @@
 ---
 name: scip-maintainability
-description: Principled maintainability review using scip-query. Finds hidden policies, scattered concepts, accidental variation, weak boundaries, and system-compression opportunities, then proposes or executes structural improvements without chasing health scores.
+description: Principled maintainability review using scip-query. Finds hidden policies, scattered concepts, accidental variation, weak boundaries, and system-compression opportunities, then proposes or executes structural improvements and verifies post-change wiring without chasing health scores.
 allowed-tools: [Bash, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
-keywords: [maintainability, architecture, compression, simplify, principal, staff, smell, hidden-policy, concept-boundary, accidental-variation, refactor]
 ---
 
 # SCIP Maintainability Review
@@ -244,12 +243,34 @@ scip-query passthrough-candidates
 scip-query similar-files
 ```
 
+Then run the post-change checks that match what the fix actually did:
+
+| Change made | Required post-check |
+| --- | --- |
+| Extracted a helper, hook, composable, component logic, or named abstraction | `scip-query incomplete-migration`; migrate every unchanged site that still contains the extracted logic or document essential variation |
+| Added a new helper, module, component, hook, or composable | `scip-query similar <new-symbol>` when symbol-like, plus `scip-query recent-duplicates --full`; delete echoes of established code |
+| Consolidated duplicated files, command handlers, adapters, or workflows | rerun the detector that motivated the change: `similar-files`, `similar-chains`, `wrapper-candidates`, `passthrough-candidates`, frontend duplicate commands, or `health --full` |
+| Added parameters, options, config flags, props, or broad option objects | `scip-query unused-params`; remove speculative inputs that no body uses |
+| Added a wrapper, adapter, facade, re-export, or forwarding layer | `scip-query wrapper-candidates`, `scip-query passthrough-candidates`, and `scip-query redundant-reexports` when exports changed |
+| Added an interface, base class, type alias, or abstraction boundary | `scip-query stale-abstractions --include-low-confidence`; prove the abstraction has real consumers and policy |
+| Changed schema, config, generated files, command descriptors, package surface, or docs-backed behavior | `scip-query co-change <file>` and `scip-query doc-drift`; update historical partners and stale docs |
+| Deleted code | `scip-query cleanup-plan --verify`; take the compiler-proven cascade or explain why not |
+
+Always finish implemented maintainability work with:
+
+```bash
+scip-query diff-impact
+scip-query reindex && scip-query diff-gate
+```
+
+Treat `diff-gate` findings as unfinished work. Fix them or state a concrete acceptance reason; do not silently report success.
+
 Report:
 
 - the named smell addressed
 - the mechanism introduced, deleted, or simplified
 - what was deliberately not compressed
-- verification results
+- verification results, including the post-change checks that matched the edit
 - commit hash, when committed
 
 ---

package/skills/scip-query/SKILL.md

@@ -2,7 +2,6 @@
 name: scip-query
 description: Router for codebase work in scip-query-indexed projects. Use whenever exploring, planning, implementing, refactoring, extracting helpers, verifying changes, hunting duplication or bloat, fixing stale docs, or cleaning up after an AI coding session — or when unsure which scip-* skill applies. Picks the right specialist skill and the commands that must run for each phase of work.
 allowed-tools: [Bash, Skill]
-keywords: [scip, codebase, explore, plan, implement, refactor, extract, verify, check-work, cleanup, duplication, bloat, drift, route, which-skill]
 ---
 
 # scip-query Router
@@ -39,6 +38,8 @@ When the user asks you to build, change, or fix something non-trivial:
 | Clean up after AI-assisted coding sessions | `scip-ai-cleanup` | `scip-query recent-duplicates`, `scip-query incomplete-migration` |
 | Reconcile docs/standards that drifted from the code | `scip-doc-reconcile` | `scip-query doc-drift <doc>` |
 | Review architecture, boundaries, hidden policies | `scip-maintainability` | `scip-query bottlenecks`, `scip-query coupling` |
+| Review React frontend reuse, components, hooks, or TSX/JSX maintainability | `scip-react-maintainability` | `scip-query react-component-duplicates --full`, `scip-query react-hook-candidates --full` |
+| Review Vue frontend reuse, SFCs, templates, or composables | `scip-vue-maintainability` | `scip-query vue-component-duplicates --full`, `scip-query vue-composable-candidates --full` |
 
 Invoke skills by name (Skill tool or slash command). If skill invocation is
 unavailable in this harness, read `~/.agents/skills/<name>/SKILL.md` and

package/skills/scip-react-maintainability/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: scip-react-maintainability
+description: React frontend maintainability review using scip-query's React component duplicate, hook candidate, large component pressure, recent-duplicate, incomplete-migration, and diff-gate commands. Use when reviewing React, TSX, JSX, or Next.js codebases; investigating duplicated components or hooks; checking frontend health pressure; or verifying agents reused React code correctly after a refactor.
+---
+
+# SCIP React Maintainability Review
+
+This skill reviews React frontends by treating components, hooks, JSX structure, and behavior lifecycles as first-class maintainability units. It uses `scip-query` evidence to decide where UI structure, state/effect/request behavior, and large components are carrying duplicated concepts or too many reasons to change.
+
+A React component duplicate candidate is a pair or group of rendered interface structures that repeat the same user-facing arrangement, controls, states, props, or data-presentation shape enough that a shared component may reduce future divergence.
+
+A React hook candidate is a pair or group of component behaviors that repeat the same state lifecycle, effects, requests, validation, persistence, callback policy, or derived-data rule enough that a shared hook may make the behavior easier to preserve.
+
+Large component pressure is a maintainability signal that one React component or file contains several kinds of knowledge that change for different reasons, such as layout structure, state management, data loading, permission policy, and styling.
+
+React health is a repo-grounded frontend pressure map. It is useful for ranking review attention, but it is not proof that code is bad and not the goal of a refactor.
+
+## Quick Start
+
+Refresh the code intelligence before trusting graph facts:
+
+```bash
+scip-query status
+scip-query reindex
+```
+
+Run the React review commands uncapped when doing a serious frontend pass. Do not combine `--full` with `--limit`.
+
+```bash
+scip-query react-component-duplicates --scope <react-source-scope> --full --json
+scip-query react-hook-candidates --scope <react-source-scope> --full --json
+scip-query react-large-component-pressure --scope <react-source-scope> --full --json
+scip-query recent-duplicates --scope <react-source-scope> --full --json
+scip-query health --scope <react-source-scope> --full --json
+```
+
+## Workflow
+
+1. Bound the review to a React source root, feature area, or changed files. Prefer the narrowest scope that still includes likely reuse partners.
+2. Run the three React commands: component duplicates, hook candidates, and large component pressure.
+3. Use `recent-duplicates` to catch newly added frontend echoes of established code.
+4. Cross-check the result sets before recommending an extraction:
+   - Component duplicate only: inspect for a shared presentational component or an existing component callers should reuse.
+   - Hook candidate only: inspect for a shared behavior, lifecycle, request pattern, validation rule, persistence rule, or derived-state policy.
+   - Both component and hook candidate: inspect for a feature-level concept that may need both a component boundary and a hook boundary.
+   - Large component only: split by reason to change, not by line count alone.
+5. Open the source files for the top candidates. Similarity is evidence to inspect, not a verdict.
+6. Check existing exports, imports, and call sites before proposing anything new:
+
+```bash
+scip-query outline <file>
+scip-query deps <file>
+scip-query rdeps <file>
+scip-query similar-files --scope <react-source-scope>
+scip-query similar <closest-existing-component-or-hook>
+```
+
+## Acting on Findings
+
+Prefer reuse before extraction. If an existing component or hook already names the concept, migrate callers to it instead of creating another one.
+
+When extracting:
+
+- Extract a component when the repeated knowledge is rendered UI structure, props, slots/children, empty/loading/error states, or design-system composition.
+- Extract a hook when the repeated knowledge is state, effects, requests, subscriptions, memoized derivations, callbacks, or persistence policy.
+- Split a large component by reason to change: data loading, permission/policy, layout shell, table/list rendering, form state, and action handling are different reasons.
+- Keep domain-specific variation at the call site when the variation is essential. Do not hide different product rules behind a boolean soup API.
+
+## Post-Change Verification
+
+After implementing a component reuse, hook extraction, or large-component split, prove both sides of the work: the new abstraction exists and the old inline copies were migrated.
+
+Run the checks that match what changed:
+
+```bash
+scip-query diff-impact
+scip-query react-component-duplicates --scope <react-source-scope> --full --json
+scip-query react-hook-candidates --scope <react-source-scope> --full --json
+scip-query react-large-component-pressure --scope <react-source-scope> --full --json
+scip-query recent-duplicates --scope <react-source-scope> --full --json
+scip-query incomplete-migration
+scip-query unused-params
+scip-query wrapper-candidates --scope <react-source-scope> --full --json
+scip-query passthrough-candidates --scope <react-source-scope> --full --json
+scip-query stale-abstractions --scope <react-source-scope> --include-low-confidence --full --json
+scip-query reindex && scip-query diff-gate
+```
+
+Use the results this way:
+
+- `incomplete-migration`: if a new hook/helper was created and wired somewhere, migrate every unchanged site that still contains the same logic or document why it is not the same behavior.
+- `recent-duplicates`: if the new component/hook is still an echo of established code, delete the echo or reuse the established concept.
+- React duplicate commands: the specific candidate pair you acted on should disappear, weaken materially, or be explicitly accepted as essential variation.
+- `unused-params`: remove speculative props/options introduced "for later."
+- wrapper/pass-through/stale checks: remove local wrapper components, hook aliases, or type abstractions that do not enforce a real policy.
+- `diff-gate`: treat every finding as unfinished work unless there is a written reason to accept it.
+
+## False Positive Checks
+
+- Shared design-system primitives, icons, labels, route names, or test IDs are not enough to justify an extraction.
+- Similar JSX with different domain lifecycles may justify a presentational component but not a hook.
+- Shared hook usage may mean the right concept is already extracted; look for drift around the shared call, not another extraction.
+- A large file creates review pressure, but it is not proof that behavior is duplicated.
+- A local wrapper is justified only when it names a real product concept, enforces a policy, or prevents drift across callers.
+
+## Reporting Shape
+
+Report findings as a frontend maintainability register:
+
+- Executive read: whether the React code is consolidating or drifting.
+- Command evidence: exact commands, scope, counts, and whether results were uncapped.
+- Candidate groups: files/components, repeated UI structure, repeated behavior, and large-component pressure.
+- Recommended action: reuse existing API, extract component, extract hook, split view, delete wrapper, or no action.
+- Post-change proof: commands rerun, candidate pairs resolved or accepted, migration completeness checked, and `diff-gate` result.