scip-query 0.10.0 → 0.10.2

package/docs/locality-analyzer-design.md

@@ -0,0 +1,193 @@
+# Locality Analyzer Design
+
+This document designs the missing analyzer family identified during the analyzer inventory: a tool that evaluates where extracted code belongs. It is intentionally a design document, not a production implementation.
+
+The problem shows up most clearly after React or Vue large-component work. An agent can reduce a large file by extracting components, hooks, helpers, or composables, but it may dump all of them into a flat folder beside the original file. That can make the size metric better while making ownership, reuse, and navigation worse.
+
+## Core Concepts
+
+Code locality is the placement relation between a source unit and the files that use it. It concerns real files, directories, imports, consumers, tests, and package boundaries; its essential characteristic is that code belongs at the nearest stable home that all legitimate consumers can reach without making the API broader than the concept deserves.
+
+A source unit is a file, symbol, component, hook, composable, type, or helper that the analyzer can name and trace. It is the smallest unit whose placement can be judged from references, imports, and directory structure.
+
+A consumer set is the set of files or symbols that import, call, render, instantiate, or otherwise rely on a source unit. Its essential role is to reveal whether a unit is private to one place, shared within a feature, shared across a domain, or actually reusable across the application.
+
+An ownership boundary is a directory, package, route, feature, domain, or module boundary that indicates who should be allowed to change a unit. It is not just a path prefix; it is the codebase's visible grouping of reasons to change.
+
+An abstraction level is the height of a unit's meaning relative to product code. A button primitive, route panel, invoice calculation, GraphQL client, and test fixture can all be TypeScript functions or components, but they belong at different levels because they serve different kinds of callers.
+
+A shared folder is a directory whose name or import pattern says that multiple nearby units may depend on it. Its essential risk is that it can either preserve local reuse or become a dumping ground that erases ownership.
+
+A global shared folder is a repository-wide shared directory such as `src/shared`, `src/lib`, `src/components`, or `packages/shared`. Its essential risk is API inflation: code placed there becomes easier to depend on from anywhere, so the placement should require cross-feature or cross-package evidence.
+
+## Command Shape
+
+Proposed command:
+
+```sh
+scip-query locality-candidates [symbol-or-file]
+```
+
+Useful options:
+
+```sh
+scip-query locality-candidates apps/web/src/routes/HorsesView.tsx --json
+scip-query locality-candidates --scope apps/web/src --since HEAD~20
+scip-query locality-candidates --changed-only --base origin/main
+```
+
+The command should be report-only at first. Its action tier is contextual signal: it guides placement and review, but it should not move files automatically.
+
+## Inputs
+
+The analyzer should combine existing evidence rather than invent a separate world model.
+
+| Input                         | Source                                                                              | Why it matters                                                        |
+| ----------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Candidate source unit         | Explicit argument, changed files, large component/view pressure, extract candidates | Chooses what placement is being judged                                |
+| Consumer files and symbols    | `refs`, `imported-by`, `rdeps`, call graph, JSX/Vue render facts                    | Shows who actually uses the unit                                      |
+| Current path and import path  | filesystem path, import graph                                                       | Reveals whether the unit is already local, feature-shared, or global  |
+| Nearest common ancestor       | consumer file paths                                                                 | Finds the smallest directory all consumers share                      |
+| Feature and route roots       | path names such as `routes`, `pages`, `features`, `modules`, `domains`              | Distinguishes product areas from generic infrastructure               |
+| Package or workspace boundary | package manifests, tsconfig references, workspace layout                            | Prevents app-local concepts from leaking into shared packages         |
+| Test adjacency                | test file paths and references                                                      | Keeps test helpers near their tests unless production consumers exist |
+| Naming evidence               | source unit name, directory names, imported symbols                                 | Distinguishes product concepts from generic primitives                |
+| Historical co-change          | `co-change`, git history                                                            | Shows whether the unit changes with one feature or several            |
+| Existing local conventions    | sibling folder names and import patterns                                            | Avoids recommendations that fight the codebase's own organization     |
+
+## Placement Tiers
+
+| Tier                   | Recommendation                                         | Strong evidence                                                                           | Common mistake caught                                                                |
+| ---------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `same-file`            | Keep the unit in the original file.                    | One consumer, no independent tests, name only makes sense inside the parent.              | Extracting a private branch into a needless helper file.                             |
+| `sibling-private`      | Put it next to the parent in a private local folder.   | Two or more consumers under one page/component folder, no outside imports.                | Creating a route-local `components` folder under global `src/components`.            |
+| `feature-local-shared` | Put it under the nearest feature/module shared folder. | Consumers span files in one feature root but not outside it.                              | Moving feature-specific hooks into app-wide `shared`.                                |
+| `domain-shared`        | Put it under a domain or bounded context folder.       | Consumers cross feature roots but share domain nouns and co-change history.               | Duplicating business rules in several features or over-generalizing them into `lib`. |
+| `app-shared`           | Put it under app-level shared UI or utility space.     | Consumers cross domains inside one app and the name is generic enough for app reuse.      | Keeping a genuinely reusable primitive hidden inside one feature.                    |
+| `package-shared`       | Put it in a shared workspace package.                  | Consumers cross package/workspace boundaries, and package API ownership is intended.      | Importing across workspace internals or copying contracts between packages.          |
+| `no-extraction`        | Do not extract, or inline it back.                     | One consumer, weak name, no independent concept, extraction only satisfies a size metric. | Size-score gaming through thin files and local indirection.                          |
+
+The output should include confidence, reasons, counterevidence, and the exact consumer set.
+
+```json
+{
+  "candidate": "apps/web/src/features/horses/HorseStatusPanel.tsx",
+  "currentTier": "app-shared",
+  "recommendedTier": "feature-local-shared",
+  "confidence": "medium",
+  "consumers": ["apps/web/src/features/horses/HorseProfile.tsx", "apps/web/src/features/horses/HorseList.tsx"],
+  "nearestCommonAncestor": "apps/web/src/features/horses",
+  "reasons": [
+    "all production consumers are inside one feature root",
+    "candidate name uses the Horses domain noun",
+    "no package or cross-domain consumers found"
+  ],
+  "counterevidence": ["component name is presentational enough that future app-level reuse is possible"],
+  "suggestedHome": "apps/web/src/features/horses/components/HorseStatusPanel.tsx"
+}
+```
+
+## Analyzer Pairing
+
+The locality analyzer should not replace existing analyzers. It should complete their story.
+
+| Existing analyzer                                    | What it says today                                    | Locality companion question                                                                           |
+| ---------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `react-large-component-pressure`                     | This React component is too large.                    | If pieces are extracted, which ones are private, feature-local, or shared?                            |
+| `vue-large-view-pressure`                            | This Vue SFC is too large.                            | Should extracted child components/composables live beside the view, in the feature, or in app shared? |
+| `extract-candidates`                                 | This function contains a possible extraction cluster. | Would the extracted helper have one real owner or a broader consumer set?                             |
+| `react-hook-candidates`, `vue-composable-candidates` | Several components repeat behavior.                   | Is the hook/composable local to one feature or reusable across domains?                               |
+| `recent-duplicates`, `echo`                          | New code duplicates older code.                       | Which existing owner should the new code reuse, and would reuse widen the wrong API?                  |
+| `incomplete-migration`                               | A helper extraction stopped halfway.                  | Is the helper in the right place for all remaining call sites?                                        |
+| `co-change`                                          | Files move together historically.                     | Does history imply a hidden shared owner or only a local synchronization point?                       |
+
+## Algorithm Sketch
+
+1. Resolve the candidate to a file or symbol.
+2. Collect direct consumers through references, imports, render facts, and reverse dependencies.
+3. Remove consumers that are tests unless the candidate is test-only.
+4. Compute the nearest common ancestor of production consumers.
+5. Identify boundary markers in and above that ancestor: `app`, `apps`, `packages`, `routes`, `pages`, `features`, `modules`, `domains`, `shared`, `components`, `hooks`, `composables`, `lib`, `utils`, `services`, `stores`, and `contracts`.
+6. Classify the current home and the smallest legitimate home.
+7. Compare names from the candidate, directories, and consumers to decide whether the concept is domain-specific or generic.
+8. Check workspace/package boundaries to prevent cross-package leakage.
+9. Use co-change history as supporting evidence, not as a hard rule.
+10. Emit a recommendation only when the consumer set and boundary evidence agree.
+
+The first implementation can avoid automatic tree moves entirely. The valuable output is a review-grade explanation: "this extracted component is global today, but all consumers are in one feature, so feature-local shared is the smallest honest home."
+
+## Precision Rules
+
+The analyzer should prefer "no confident recommendation" over pretending all placement is obvious.
+
+Report `same-file` or `no-extraction` when a candidate has one consumer and no independent concept name.
+
+Report `sibling-private` when all consumers sit below one component, route, or view folder and no outside production import exists.
+
+Report `feature-local-shared` when consumers share a feature root and imports do not cross into other feature roots.
+
+Report `domain-shared` only when path names, symbol names, or co-change evidence show the same product domain across multiple feature roots.
+
+Report `app-shared` only when consumers cross domains inside one app and the unit is not named after one feature.
+
+Report `package-shared` only when consumers cross package boundaries and package exports make that sharing intentional.
+
+Downrank a recommendation when imports come only through barrels, tests are the only second consumer, the candidate name is generic but behavior is domain-specific, or the nearest common ancestor is the repo root.
+
+## Skill-First Option
+
+Before production implementation, this can ship as a bundled workflow skill.
+
+Proposed skill name:
+
+```text
+scip-locality-review
+```
+
+The skill would tell agents to run:
+
+```sh
+scip-query plan-context <target> --full
+scip-query imported-by <symbol>
+scip-query rdeps <file>
+scip-query co-change <file> --full
+scip-query react-large-component-pressure <scope> --full
+scip-query vue-large-view-pressure <scope> --full
+```
+
+Then it would require the agent to answer:
+
+1. What is the exact consumer set?
+2. What is the nearest common owner all consumers share?
+3. Is the concept product-specific, feature-specific, app-generic, or package-level?
+4. Does the current path make the API wider than the consumer set requires?
+5. Would a move reduce imports and ownership confusion without creating a new global dumping ground?
+
+This is a good first step because it turns the product question into a repeatable checklist while we gather validation labels for the eventual command.
+
+## Validation Plan
+
+Use the validation corpus from `docs/analyzer-validation-protocol.md` and track the work under `docs/analyzer-validation-ledger.md`.
+
+For React, inspect Vega_2.0 large components and hook candidates. A true positive is a recommendation that would place an extracted unit closer to its actual consumers without hiding a real shared primitive.
+
+For Vue, inspect Stable_Management large views and composable candidates. A true positive is a recommendation that distinguishes route-local child components from feature-level composables and app-level UI primitives.
+
+For scip-query itself, inspect analyzer/helper extractions. A true positive is a recommendation that keeps detector-private helpers near their detector unless multiple detector families actually consume them.
+
+For Rust smoke coverage, run the command only after SCIP data supports the same source-unit questions. Until then, locality validation on Rust should be marked unsupported rather than failed.
+
+Validation result: `docs/validation/2026-06-21-locality-analyzer-validation-result.md` recommends a report-only or skill-first implementation, with `actionTier: "signal"` and explicit consumer-coverage caveats. React `.tsx` samples had usable `rdeps` evidence, but Vue SFC samples had weak reverse-dependency coverage, so the first implementation must not recommend concrete destinations unless exact consumers are known.
+
+## Score Integration
+
+Locality findings should not immediately reduce health like dead code. They are contextual signals.
+
+The health score can later use them as signal backlog pressure when they combine with other evidence:
+
+- Large component pressure plus globalized local children.
+- Extract candidates plus one-consumer helper files.
+- Recent duplicates plus a clear existing local owner.
+- Co-change clusters plus no shared owner directory.
+
+The score should not punish a single "could be more local" suggestion. It should punish repeated evidence that code organization is being flattened until ownership is unclear.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "scip-query",
-  "version": "0.10.0",
-  "description": "Language-agnostic code intelligence CLI powered by SCIP indexes",
+  "version": "0.10.2",
+  "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,
@@ -147,6 +149,10 @@
       "import": "./dist/queries/isolated.js",
       "types": "./dist/queries/isolated.d.ts"
     },
+    "./queries/locality-candidates": {
+      "import": "./dist/queries/locality-candidates.js",
+      "types": "./dist/queries/locality-candidates.d.ts"
+    },
     "./queries/members": {
       "import": "./dist/queries/members.js",
       "types": "./dist/queries/members.d.ts"
@@ -195,6 +201,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"
@@ -231,6 +261,10 @@
       "import": "./dist/queries/unused-params.js",
       "types": "./dist/queries/unused-params.d.ts"
     },
+    "./queries/unused-imports": {
+      "import": "./dist/queries/unused-imports.js",
+      "types": "./dist/queries/unused-imports.d.ts"
+    },
     "./queries/wrapper-candidates": {
       "import": "./dist/queries/wrapper-candidates.js",
       "types": "./dist/queries/wrapper-candidates.d.ts"
@@ -245,14 +279,16 @@
     }
   },
   "scripts": {
-    "build": "tsup",
+    "build": "node --max-old-space-size=8192 ./node_modules/tsup/dist/cli-default.js",
     "dev": "tsup --watch",
+    "format": "prettier --write \"{src,tests,scripts}/**/*.{ts,tsx,js,mjs,json}\" \"*.{ts,js,json}\"",
+    "format:check": "prettier --check \"{src,tests,scripts}/**/*.{ts,tsx,js,mjs,json}\" \"*.{ts,js,json}\"",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src tests tsup.config.ts",
+    "lint": "npm run format:check && eslint src tests tsup.config.ts",
     "calibrate": "node scripts/accuracy-calibration.mjs",
-    "docs:commands": "vite-node scripts/render-command-reference.ts",
+    "docs:commands": "vite-node scripts/render-command-reference.ts --write",
     "prepublishOnly": "npm run build",
     "postinstall": "node dist/postinstall.js || true"
   },
@@ -280,6 +316,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",
@@ -309,6 +347,7 @@
     "@types/node": "^22.10.0",
     "eslint": "^10.2.0",
     "globals": "^17.5.0",
+    "prettier": "^3.8.4",
     "tsup": "^8.3.0",
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.58.1",

package/skills/scip-directory-architecture/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: scip-directory-architecture
+description: Review and improve repository directory architecture with scip-query evidence. Use when the user asks to design, evaluate, reorganize, or migrate source folder structure; identify feature/module ownership boundaries; turn a messy or AI-generated codebase into clearer folders; decide whether locality boundaries are mature enough for config; or plan safe directory migrations without guessing from filenames alone.
+---
+
+# SCIP Directory Architecture
+
+## Overview
+
+Use this skill to turn source layout questions into an evidence-backed architecture review. Do not treat the current folder tree as authoritative, and do not invent an "optimal" structure without proving the ownership concepts from code, tests, docs, and dependency evidence.
+
+A directory architecture is the filesystem arrangement of source files by their main reason to change. Its defining trait is that a maintainer can predict where a concept belongs before reading every import.
+
+An ownership boundary is a folder, package, module, or convention that groups code around one stable responsibility. Its defining trait is that code inside the boundary should usually change for the same kind of reason.
+
+A target structure is a proposed future folder layout for the repo or scope. Its defining trait is that it expresses the desired ownership model, not merely a prettier tree.
+
+A migration slice is the smallest set of file moves and import updates that can be verified independently. Its defining trait is that it reduces one structural ambiguity without requiring the whole architecture to move at once.
+
+## Non-Negotiables
+
+1. Start with evidence, not taste. Refresh the index when stale, then ground claims in `scip-query` outputs plus project docs and tests.
+2. Separate review from migration. A directory architecture review may propose moves; it does not move files unless the user asked for implementation or approved a specific migration slice.
+3. Preserve working conventions. Existing boundaries are not wrong just because they are broad; central folders such as `errors`, `routes`, `workflows`, `schemas`, `contracts`, or `features` may be doing real work.
+4. Do not reward generic `shared`. A shared folder is justified only when the shared concept has a name, owner, and consumers across real boundaries.
+5. Treat messy repos honestly. If ownership concepts are not stable, produce a discovery map and decision list instead of pretending the repo has a clean target structure.
+6. Prefer small verified moves. Broad reorganizations need staged migration slices with import updates, tests, `scip-query reindex`, and `scip-query diff-gate`.
+
+## Workflow
+
+### 1. Bound the Question
+
+Identify whether the user wants:
+
+- a review of the existing structure;
+- a proposed target structure;
+- a locality config decision;
+- a migration plan;
+- or an actual file-moving implementation.
+
+If the user asks for "the best folder structure," translate that into: "What ownership model is supported by this repo's code, tests, product domains, and change history?"
+
+### 2. Refresh and Inventory
+
+Run:
+
+```bash
+scip-query status
+scip-query reindex
+scip-query stats
+find . -maxdepth 3 -type d | sort
+```
+
+Read durable project guidance before judging structure:
+
+```bash
+rg -n "architecture|structure|feature|module|boundary|shared|workflow|route|contract|domain|ownership" AGENTS.md README.md docs agent-os .codex -g '!node_modules'
+```
+
+Use `rg --files` to sample real files in each important folder. Ignore generated, build, coverage, vendored, and dependency directories unless they are part of the architecture question.
+
+### 3. Build the Evidence Map
+
+Use these probes as evidence, not as verdicts:
+
+```bash
+scip-query system <scope>
+scip-query files <pattern>
+scip-query surface <scope>
+scip-query deps <file>
+scip-query rdeps <file>
+scip-query change-surface <file>
+scip-query plan-context <file-or-symbol>
+scip-query locality-candidates --json --full
+scip-query cycles
+scip-query co-change
+scip-query similar-files --min-similarity 0.6 --min-deps 3
+scip-query similar-chains --min-similarity 0.5
+scip-query recent-duplicates
+scip-query drift
+```
+
+For each folder under review, record:
+
+- real-world concept or product area represented by the folder;
+- public exports, entry points, routes, commands, or package surfaces;
+- main consumers and cross-boundary consumers;
+- tests that define the folder's behavior;
+- co-change partners and repeated edit patterns;
+- duplicated or parallel folder patterns;
+- docs or standards that claim ownership rules.
+
+### 4. Classify Boundary Maturity
+
+Classify each candidate folder:
+
+- Mature: repeated, documented, and enforced by imports, tests, routes, packages, standards, or review history.
+- Emerging: meaningful and partly repeated, but not yet consistent enough to configure or enforce.
+- Accidental: a convenience bucket, legacy pile, generated artifact, recent edit cluster, or mixed folder with unrelated reasons to change.
+
+A slop codebase is a codebase whose files are arranged by accident, convenience, or recent edits rather than stable ownership rules. Its defining trait is that directory names do not reliably predict where code should live. For this case, stop at discovery and decision prompts unless the user explicitly asks for a first migration slice.
+
+### 5. Propose the Target Structure
+
+Produce an architecture proposal with this shape:
+
+````markdown
+# Directory Architecture Review
+
+## Scope
+## Current Structure Map
+## Boundary Maturity
+
+| Boundary | Evidence | Maturity | Judgment |
+| --- | --- | --- | --- |
+
+## Target Structure
+
+```text
+src/
+  ...
+```
+
+## Move Ledger
+
+| Slice | Current files | Proposed home | Why | Verification |
+| --- | --- | --- | --- | --- |
+
+## Locality Config
+## Deferred Decisions
+## Migration Order
+````
+
+The target structure should name ownership concepts, not just folder labels. Prefer existing names when they already carry meaning. Introduce a new folder only when it removes ambiguity for multiple files or consumers.
+
+### 6. Decide What Not to Move
+
+Explicitly list no-move decisions when:
+
+- a broad consumer set proves a central boundary is useful;
+- a folder is route-facing, package-facing, or contract-facing;
+- consumers cross boundaries because the concept is infrastructure;
+- moving would hide a domain-specific concept under generic `shared`;
+- the evidence is too weak and needs a human ownership decision.
+
+### 7. Implement Only a Migration Slice
+
+When the user asks to proceed, pick the smallest high-confidence slice. Before editing, state:
+
+- files to move;
+- imports/exports/tests/docs to update;
+- expected verification commands;
+- rollback risk.
+
+Then move files with normal filesystem tools, update imports with project tooling where available, and run:
+
+```bash
+scip-query reindex
+scip-query incomplete-migration
+scip-query recent-duplicates
+scip-query co-change <moved-file-or-config>
+scip-query diff-gate
+```
+
+Also run the repo's normal tests or typecheck for the affected workspace. If the migration adds or changes `.scipquery.json` locality settings, run:
+
+```bash
+scip-query config-validate
+scip-query locality-candidates --json --full
+```
+
+## Output Rules
+
+- Lead with findings and judgments, not command transcripts.
+- Every proposed boundary needs evidence from at least two independent signals or a clear note that it is only a candidate.
+- Every proposed move needs a verification path.
+- For messy repos, output "discovery mode" and decision questions instead of a fake complete architecture.
+- For implementation, never batch unrelated folder moves just because they fit the same target structure.

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` |
+| 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
@@ -38,7 +37,10 @@ When the user asks you to build, change, or fix something non-trivial:
 | Find dead code, duplication, or structural bloat | `scip-debloat` | `scip-query health` |
 | 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 or redesign source folder structure and ownership boundaries | `scip-directory-architecture` | `scip-query locality-candidates --json --full`, `scip-query similar-files --full` |
+| Review architecture, hidden policies, weak boundaries beyond folder structure | `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