scip-query 0.10.12 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scip-query",
-  "version": "0.10.12",
+  "version": "0.12.0",
   "description": "Evidence and verification for AI coding agents: map code, reuse concepts, finish migrations, and gate diffs.",
   "type": "module",
   "main": "dist/index.js",
@@ -9,15 +9,15 @@
     "scip-query": "dist/cli.js"
   },
   "files": [
+    "CHANGELOG.md",
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "docs/assets/**/*",
     "docs/*.md",
     "scripts/build-scip-windows.mjs",
     "scripts/evidence-product-contract.mjs",
-    "skills/**/SKILL.md",
-    "skills/**/agents/*.yaml",
-    "vendor/scip/**/*"
+    "skills/**/*.md",
+    "skills/**/agents/*.yaml"
   ],
   "sideEffects": false,
   "exports": {
@@ -109,6 +109,10 @@
       "import": "./dist/queries/doc-drift.js",
       "types": "./dist/queries/doc-drift.d.ts"
     },
+    "./queries/duplicate-bodies": {
+      "import": "./dist/queries/duplicate-bodies.js",
+      "types": "./dist/queries/duplicate-bodies.d.ts"
+    },
     "./queries/drift": {
       "import": "./dist/queries/drift.js",
       "types": "./dist/queries/drift.d.ts"
@@ -261,6 +265,14 @@
       "import": "./dist/queries/trace.js",
       "types": "./dist/queries/trace.d.ts"
     },
+    "./queries/twin-ab": {
+      "import": "./dist/queries/twin-ab.js",
+      "types": "./dist/queries/twin-ab.d.ts"
+    },
+    "./queries/twin-drift": {
+      "import": "./dist/queries/twin-drift.js",
+      "types": "./dist/queries/twin-drift.d.ts"
+    },
     "./queries/unused-params": {
       "import": "./dist/queries/unused-params.js",
       "types": "./dist/queries/unused-params.d.ts"
@@ -290,13 +302,14 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "lint": "npm run format:check && eslint src tests tsup.config.ts",
+    "lint": "npm run format:check && eslint src tests tsup.config.ts && node scripts/check-skill-links.mjs",
     "build:scip-windows": "node scripts/build-scip-windows.mjs",
     "bench:evidence-products": "node scripts/evidence-product-contract.mjs",
     "calibrate": "node scripts/accuracy-calibration.mjs",
     "docs:commands": "vite-node scripts/render-command-reference.ts --write",
-    "prepublishOnly": "npm run build && npm run build:scip-windows",
-    "postinstall": "node dist/postinstall.js || true"
+    "prepublishOnly": "npm run publish:scip-windows && npm run build",
+    "postinstall": "node dist/postinstall.js || true",
+    "publish:scip-windows": "vite-node scripts/publish-scip-windows.ts"
   },
   "keywords": [
     "scip",
@@ -333,6 +346,7 @@
   "optionalDependencies": {
     "@sourcegraph/scip-typescript": "^0.4.0",
     "scip-python-plus": "^0.7.4",
+    "scip-query-scip-windows": "0.12.0",
     "tree-sitter": "0.21.1",
     "tree-sitter-c": "0.23.2",
     "tree-sitter-c-sharp": "0.23.1",
@@ -358,5 +372,23 @@
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.58.1",
     "vitest": "^3.0.0"
+  },
+  "allowScripts": {
+    "better-sqlite3@12.9.0": true,
+    "esbuild@0.27.7": true,
+    "fsevents@2.3.3": true,
+    "tree-sitter@0.21.1": true,
+    "tree-sitter-c@0.23.2": true,
+    "tree-sitter-c-sharp@0.23.1": true,
+    "tree-sitter-cpp@0.23.4": true,
+    "tree-sitter-java@0.23.5": true,
+    "tree-sitter-javascript@0.23.1": true,
+    "tree-sitter-kotlin@0.3.8": true,
+    "tree-sitter-php@0.23.12": true,
+    "tree-sitter-python@0.23.4": true,
+    "tree-sitter-ruby@0.23.1": true,
+    "tree-sitter-rust@0.23.1": true,
+    "tree-sitter-scala@0.24.0": true,
+    "tree-sitter-typescript@0.23.2": true
   }
 }

package/scripts/build-scip-windows.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from 'node:url';
 const SCIP_VERSION = process.env.SCIP_VERSION ?? 'v0.8.1';
 const SCIP_REPO_URL = process.env.SCIP_REPO_URL ?? 'https://github.com/scip-code/scip.git';
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const VENDOR_DIR = join(ROOT, 'vendor', 'scip');
+const VENDOR_DIR = join(ROOT, 'packages', 'scip-windows');
 
 const TARGETS = [
   { goarch: 'amd64', packageArch: 'x64' },
@@ -45,20 +45,23 @@ try {
   writeFileSync(
     join(VENDOR_DIR, 'README.md'),
     [
-      '# Managed scip binaries',
+      '# scip.exe release assets',
       '',
       `These binaries are built from ${SCIP_REPO_URL} at ${SCIP_VERSION}.`,
-      'They are included so Windows installs can run `scip-query reindex` without requiring Go or WSL.',
+      'They are NOT bundled into the npm package. Upload each as a GitHub release',
+      'asset (scip-win32-<arch>.exe) and pin url + sha256 in',
+      'src/runtime/scip-windows-assets.ts before publishing — scip-query downloads',
+      'and checksum-verifies them on demand so Windows `reindex` works without',
+      'requiring Go or WSL.',
       '',
-      'Run `npm run build:scip-windows` before publishing to refresh them.',
+      'Run `npm run build:scip-windows` to (re)build these before publishing.',
       '',
     ].join('\n'),
   );
 
   for (const target of TARGETS) {
-    const outputDir = join(VENDOR_DIR, `win32-${target.packageArch}`);
-    const outputPath = join(outputDir, 'scip.exe');
-    mkdirSync(outputDir, { recursive: true });
+    const outputPath = join(VENDOR_DIR, `scip-win32-${target.packageArch}.exe`);
+    mkdirSync(VENDOR_DIR, { recursive: true });
 
     run('go', ['build', '-trimpath', '-ldflags=-s -w', '-o', outputPath, './cmd/scip'], {
       cwd: checkoutDir,

package/skills/_shared/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: _shared
+description: Shared scip-query reference for bundled skills.
+disable-model-invocation: true
+---
+
+# scip-query Shared Reference
+
+This is shared reference for scip-query skills. Load it when another skill says to use the shared evidence, lookup, postcheck, or subagent rules.
+
+## Evidence Contract
+
+A SCIP index is the compiler-derived map of a repository's source files, symbols, references, imports, calls, and dependencies. What makes it different from text search is that it records what the language toolchain can identify, so code claims can point to definitions and consumers rather than matching strings.
+
+A graph fact is a claim produced from that index, such as a definition line, reference site, caller, callee, dependency, reverse dependency, or affected consumer. Use graph facts for code behavior, ownership, and blast-radius claims.
+
+Before trusting graph facts, run:
+
+```bash
+scip-query status --capabilities
+```
+
+If freshness is `fresh`, continue. If it is `stale`, `missing`, or `unknown`, run:
+
+```bash
+scip-query reindex
+```
+
+Every file path, line number, symbol relationship, and behavior claim in a plan, report, or review must cite the command that produced it. If `scip-query` cannot answer a question because the target is not indexed, say so and use the narrowest other evidence available.
+
+## Lookup
+
+Use partial symbol names without parentheses:
+
+```bash
+scip-query code parseConfig
+scip-query call-graph runCommand
+scip-query trace loadSettings
+```
+
+If lookup is ambiguous or missing:
+
+1. Try a shorter symbol name.
+2. Run `scip-query outline <file>`.
+3. Run `scip-query trace <name>`.
+4. Use `scip-query code 'path/to/file.ts:START-END'` when you know the file range.
+
+## Command Families
+
+<!-- BEGIN GENERATED COMMAND FAMILIES -->
+
+This syntax catalog is generated from the CLI command descriptors.
+
+### Indexing
+
+```bash
+scip-query reindex # Index the codebase and convert to SQLite
+scip-query augment-sources # Add source files skipped by upstream SCIP indexers to the SQLite documents table
+scip-query augment-vue # Add compiler-resolved Vue SFC references to the SQLite index using Volar
+```
+
+### Core
+
+```bash
+scip-query stats # Show index statistics
+```
+
+### Navigation
+
+```bash
+scip-query files <pattern> # Find files matching a pattern
+scip-query methods <className> # List methods of a class (with line ranges)
+scip-query refs <symbol> # Find all files referencing a symbol
+scip-query trace <symbol> # Trace a symbol: definition + all references
+scip-query deps <file> # Files this file depends on (internal)
+scip-query rdeps <file> # Files that depend on this file/module
+scip-query system <module> # Full module map: files, symbols, deps in/out
+scip-query surface <module> # What symbols consumers actually use from this module
+scip-query imports <file> # What symbols does this file import?
+scip-query imported-by <symbol> # Which files import this symbol?
+scip-query outline <file> # Tree view of symbols in a file, with line ranges
+scip-query members <symbol> # All children of a symbol (methods, fields, nested types)
+scip-query by-kind <kind> # Find symbols by SCIP kind (class, interface, enum, function, etc.)
+scip-query kind-counts # Histogram of symbol kinds in the codebase
+scip-query hierarchy <symbol> # Show a symbol's ancestry chain (method → class → module)
+scip-query code <symbol> # Read the source code for a symbol (bounded to its definition range)
+scip-query dataflow <symbol> # Reference-level dataflow: definition sites, usage sites, producers, consumers
+scip-query slice <symbol> # Reference-level program slice: what affects this (backward) or what this affects (forward)
+```
+
+### Cleanup
+
+```bash
+scip-query dead [scope] # Find dead code and file-internal symbols (no cross-file consumers)
+scip-query unused-imports <file> # Find imports not referenced in the same file
+scip-query isolated # Find completely orphaned symbols (no references at all)
+scip-query similar [symbol] [other] # Find heuristic function similarity candidates from callee fingerprints
+scip-query similar-files [file] # Find heuristic similar-file candidates from dependency profiles
+scip-query react-component-duplicates [file] # Find heuristic duplicated React component structure candidates from JSX tags, props, events, and bindings
+scip-query react-hook-candidates [file] # Find heuristic React hook extraction candidates from shared state, effects, requests, and handlers
+scip-query react-large-component-pressure [file] # Find heuristic large React component pressure candidates from component lines, JSX structure, and hook behavior
+scip-query vue-component-duplicates [file] # Find heuristic duplicated Vue component structure candidates from template tags, bindings, slots, and directives
+scip-query vue-composable-candidates [file] # Find heuristic Vue composable extraction candidates from shared state, effects, requests, and template bindings
+scip-query vue-large-view-pressure [file] # Find heuristic large Vue view pressure candidates from template, script, style, and external script line counts
+scip-query similar-chains # Find heuristic similar-chain candidates from dependency flows
+scip-query extract-candidates # Find heuristic extraction candidates from isolated callee clusters
+scip-query locality-candidates [symbol-or-file] # Find directory-locality and ancestry candidates from consumer ownership
+scip-query cleanup-plan # Ordered, batched deletion plan: graph-fact dead code plus the cascade candidates it unlocks
+scip-query cleanup-apply # Apply a compiler-verified cleanup-plan batch to the working tree
+scip-query recent-duplicates # Directional duplicate candidates: recent code that re-implements established callable, React, or Vue code
+scip-query doc-drift [doc] # Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped
+scip-query unused-params # Speculative-generality candidates: trailing parameters no body ever uses (TS/JS)
+scip-query drift [module] # Detect heuristic drift candidates: unused imports and layer violations by default; pass --patterns for pattern deviations too
+scip-query wrapper-candidates # Find heuristic wrapper candidates only called by one consumer (high false-positive rate on codebases with intentional layering/ambient types — treat as exploration, not findings)
+scip-query passthrough-candidates # Find heuristic passthrough candidates that forward to one callee
+scip-query stale-abstractions # Find heuristic stale abstraction candidates with 0-1 consumers (high false-positive rate on codebases with intentional layering/ambient types — treat as exploration, not findings)
+scip-query complexity-hotspots # Find heuristic complexity hotspot candidates from LOC x fan-in x fan-out
+scip-query convergence <symbol1> <symbol2> # Deprecated alias for similar <symbol1> <symbol2> --plan
+scip-query redundant-reexports # Find barrel re-exports that nobody imports through
+scip-query duplicate-bodies # Find exact duplicate small-body candidates across files
+scip-query twin-drift # Twin drift candidates: same-name (or near-name) functions across files with diverged bodies
+scip-query twin-ab <symbolA> <symbolB> # Generate a behavioral A/B scaffold comparing two same-concept twins (scip-integrity-audit drill 5) — a ready-to-fill vitest file, not an auto-executor
+scip-query similar-signatures # Find functions with near-identical type signatures (same shape)
+```
+
+### Graph
+
+```bash
+scip-query hotspots # Most-referenced symbols in the codebase (choke points)
+scip-query fan-in [symbol] # How many files reference a symbol (or top fan-in across codebase)
+scip-query fan-out [file] # How many external symbols a file uses (or top fan-out across codebase)
+scip-query coupling [file1] [file2] # Coupling between two files, or top coupled pairs in codebase
+scip-query cycles # Detect circular dependency chains between files
+scip-query bottlenecks # Find coupling hubs: high fan-in AND high fan-out
+scip-query deep-chains # Find the longest transitive dependency chains
+scip-query call-graph <symbol> # Show incoming callers and outgoing callees for a symbol
+```
+
+### Impact
+
+```bash
+scip-query affected <symbol> # Transitive closure of symbols that could break if this symbol changes
+scip-query change-surface <file> # Pre-change briefing: exports, consumers, and blast-radius risk
+scip-query co-change [file] # Files that change together in git history without a dependency edge — hidden coupling candidates
+scip-query diff-gate # Gate the current diff: echo candidates, incomplete migrations, missing co-change partners, unedited twin partners (advisory), uncited doc updates, unused params, new dead symbols; exit 1 on blocking findings
+scip-query incomplete-migration # Partially-completed extraction candidates: new helpers in the diff wired into some sites while similar un-migrated sites remain
+scip-query diff-impact # Compute changed symbols and downstream consumers from current git diff
+```
+
+### Formal Models
+
+```bash
+scip-query tla <operation> [spec] # TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation
+```
+
+### Planning
+
+```bash
+scip-query plan-context <target> # Pre-edit planning context for a symbol, file, or module
+```
+
+### Health
+
+```bash
+scip-query self-audit # Score cheap evidence paths against the best available semantic/source oracle on sampled symbols
+scip-query health # Composite codebase health report with prioritized action list
+scip-query complexity <symbol> # Per-symbol complexity: branches, cyclomatic estimate, fan-in/out, callees
+```
+
+### Maintenance
+
+```bash
+scip-query bench # Benchmark indexing and command runtimes for this repository
+scip-query install-skills # Install skills (_shared, scip-query, scip-setup, scip-cleanup-audit, scip-cleanup-improve, scip-integrity-audit, scip-twin-drift, scip-claim-audit, scip-probe-reachability, scip-hyper-optimization, scip-api-impact, scip-concrete-plan, scip-conductor, scip-debug, scip-explore, scip-triage-issue, scip-diagram, scip-doc-reconcile, scip-directory-architecture, scip-maintainability, scip-react-maintainability, scip-vue-maintainability, scip-verify, scip-language-playbook, scip-tla-model-system) into Claude Code, Codex, and shared agent roots
+scip-query setup-hooks # Install or refresh project-local Codex and Claude Code lifecycle hooks
+scip-query check-deps # Check whether scip-query and the detected language indexers are actually runnable
+scip-query capabilities # Report which evidence and verification capabilities are available in this project
+scip-query capability-matrix # Deprecated alias for capabilities --matrix
+scip-query init # Create a .scipquery.json config file for this project
+scip-query config-validate # Validate .scipquery.json, including structured suppressions and declared coupling groups
+scip-query suppress <id> # Record an accepted finding in .scipquery.json with a required reason
+scip-query doctor # Diagnose config, index freshness, dependency readiness, and project capabilities
+scip-query setup # Bootstrap this project: install agent skills, refresh the index, verify capabilities, and report health
+scip-query 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
+scip-query setup-ci # Write a GitHub Actions workflow that runs scip-query reindex and diff-gate on pull requests
+scip-query uninstall # Remove scip-query-owned skill links, project hooks, and managed agent setup blocks
+scip-query watch # Watch for file changes in the foreground and reindex automatically
+scip-query status # Show index status for this project
+```
+
+<!-- END GENERATED COMMAND FAMILIES -->
+
+## Detector Reliability
+
+Calibrated against two external production repos on 2026-07-01
+(docs/validation/2026-07-01-external-calibration-*.md). Weight findings by
+measured precision, not by volume:
+
+- **Strong signal** — `complexity-hotspots` (~90%), `recent-duplicates` (~75%), graph facts (`refs`, `trace`, `deps`), compiler-verified `cleanup-plan --verify`.
+- **Good with review** — `duplicate-bodies`, `similar`, `co-change`, `doc-drift`, `twin-drift` (post-retune defaults).
+- **Exploration only** — `wrapper-candidates`, `stale-abstractions`, `drift --patterns`: near-zero precision on codebases with intentional layering or ambient types. Never file their findings without reading the cited code.
+- **Advisory gate findings** (marked `(advisory)`) never block; they are context, not obligations.
+- **False-dead archetypes (2026-07-02 remediation, docs/plans/2026-07-02-followups.md items 1-3)**: `import type`-only consumers (incl. tsconfig `paths`-aliased specifiers) and pnpm/npm/yarn workspace cross-package consumers (incl. unbuilt `dist/` exports maps) are now resolved by the shared reference-counting layer that `dead`/`isolated`/`new-dead`/`stale-abstractions`/`production-callables` all consume; Vue `<script setup>` composable consumers were already correctly resolved (verified live, no code change needed). One narrow residual gap remains: a symbol with an **ambiguous leaf name** (a same-named definition exists elsewhere in the project) reached only through a **re-exporting barrel file** in a workspace package can still misattribute — `new-dead` labels that specific shape `unconfirmed (cross-package ambiguous-name resolution gap)` with `evidence: "heuristic"` and lowered confidence instead of asserting `dead`; treat those as "verify manually," not as a fact. Everything else in this class is a normal graph-fact `dead` claim again — confirm with `refs` when in doubt, same as any other finding.
+- **Ledger nudges**: when `diff-gate --hook` reports "this check is rarely acted on in this repo", either tune that check's config, suppress the standing findings with reasons, or consciously accept the noise — do not let unresolved findings accumulate as wallpaper.
+
+## Diff Gate Checks
+
+`diff-gate` runs nine checks (`--skip <check>` accepts any of these): `echo` (recent-duplicate-style echoes in the diff), `incomplete-migration`, `co-change-partner` (missing historically-paired file), `twin-partner` (advisory — unedited same-name twin), `coverage-contract` (a configured `coverageContracts` enumeration drifted from its ground truth — see `scip-setup`), `doc-reference` (uncited or stale doc claim), `unused-params`, `new-dead` (dead code introduced by this diff), and `baseline` (only with `--baseline`: compares against the committed `.scipquery-baseline.json`, distinct from `health --baseline`). Findings print grouped under a `Root-cause groups (N):` header before the flat list — a group's remediation usually clears every finding under it, and the same remediation may then repeat in the flat list below; that repetition is expected, not a separate issue. `--baseline` findings additionally carry an `actionTier`: `direct` (act on this finding alone), `signal` (corroborating evidence — read before acting), `support` (context only).
+
+## Postchecks
+
+Run the rows that match the actual edit:
+
+| Change made | Check |
+| --- | --- |
+| Extracted a helper or abstraction | `scip-query incomplete-migration --json --full` |
+| Added a helper, module, component, hook, composable, or adapter | `scip-query similar <symbol> --json --full` and `scip-query recent-duplicates --json --full` |
+| Added parameters, options, props, config flags, or broad option objects | `scip-query unused-params --json --full` |
+| Added a wrapper, facade, forwarding layer, alias, or re-export | `scip-query wrapper-candidates --json --full`, `scip-query passthrough-candidates --json --full`, and `scip-query redundant-reexports` when exports changed |
+| Added an interface, base class, adapter contract, or type alias | `scip-query stale-abstractions --json --full` |
+| Changed schema, config, generated files, public contracts, command descriptors, or docs-backed behavior | `scip-query co-change <file> --json --full` and `scip-query doc-drift --json --full` |
+| Deleted code | `scip-query cleanup-plan --verify --json` |
+| Changed React components or hooks | the React frontend commands above |
+| Changed Vue SFCs or composables | the Vue frontend commands above |
+
+Every implemented change ends with:
+
+```bash
+scip-query status --capabilities
+scip-query diff-gate --json
+```
+
+Fix findings or record a specific acceptance reason. Do not report success while a diff-gate finding is unexplained.
+
+## Subagents
+
+When a subagent is used for scip-query evidence, include these rules in its prompt:
+
+```text
+Use scip-query for all code references. Do not use grep, rg, cat, or file reads as evidence for code behavior. Every file path, line number, and behavioral claim must cite the exact scip-query command that produced it. If scip-query cannot verify a claim, say so.
+```
+
+Reject subagent findings that cite text search or raw file reads as code evidence when graph facts were required.

package/skills/_shared/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Shared Reference"
+  short_description: "Reference only - not a workflow"
+  default_prompt: "Use $_shared only as reference material loaded by another scip-query workflow skill; do not invoke it as the owning workflow."

package/skills/scip-api-impact/SKILL.md

@@ -1,18 +1,48 @@
 ---
 name: scip-api-impact
-description: Assess and plan public API, module boundary, schema, route, CLI, config, or exported-surface changes with scip-query evidence. Use when the user asks what will break, who consumes an API, how to migrate a boundary, whether a signature change is safe, or how to coordinate docs/tests/generated artifacts.
+description: Assess API impact with scip-query evidence. Use before changing public exports, module boundaries, schemas, routes, CLI commands, config fields, generated artifacts, signatures, docs-backed behavior, or consumer migrations.
+commands:
+  - template: "scip-query surface <module-or-package>"
+    when: "Identify the surface: what consumers actually use from the module."
+  - template: "scip-query refs <symbol>"
+    when: "Find consumers: every direct reference to the surface symbol."
+  - template: "scip-query affected <symbol> --json"
+    when: "Find consumers: transitive blast radius of the change."
+  - template: "scip-query co-change <file> --json --full"
+    when: "Find hidden partners: historically coupled files without a dependency edge."
+  - template: "scip-query doc-drift --json --full"
+    when: "Find hidden partners: docs that describe the surface and may need an update."
+  - template: "scip-query unused-params --json --full"
+    when: "Choose migration shape: reject speculative new parameters."
 ---
 
-# SCIP API Impact
+# scip-api-impact
 
-Use this skill before changing a public surface. A public surface is a callable, export, route, schema, config field, CLI command, generated artifact, or documented behavior that other code or users can depend on. Its defining trait is that a local edit can require coordinated consumer, docs, test, or migration changes outside the implementation file.
+Use this skill before changing a public surface. A public surface is a callable, export, route, schema, config field, CLI command, generated artifact, or documented behavior that other code or users can depend on. Its defining trait is that a local edit can require coordinated consumer, docs, tests, or migration changes outside the implementation file.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query surface <module-or-package>` | What symbols consumers actually use from this module | Identify the surface: what consumers actually use from the module. |
+| `scip-query refs <symbol>` | Find all files referencing a symbol | Find consumers: every direct reference to the surface symbol. |
+| `scip-query affected <symbol> --json` | Transitive closure of symbols that could break if this symbol changes | Find consumers: transitive blast radius of the change. |
+| `scip-query co-change <file> --json --full` | Files that change together in git history without a dependency edge — hidden coupling candidates | Find hidden partners: historically coupled files without a dependency edge. |
+| `scip-query doc-drift --json --full` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | Find hidden partners: docs that describe the surface and may need an update. |
+| `scip-query unused-params --json --full` | Speculative-generality candidates: trailing parameters no body ever uses (TS/JS) | Choose migration shape: reject speculative new parameters. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
 
 ## Rules
 
-1. Identify the actual surface before planning the change.
-2. Use scip-query to find direct consumers, reverse dependencies, transitive blast radius, and historical co-change partners.
+1. Identify the actual surface before planning.
+2. Find direct consumers, reverse dependencies, transitive blast radius, and historical co-change partners.
 3. Treat docs, generated files, tests, and config as part of the API when they describe or enforce the surface.
-4. Prefer backward-compatible migration plans when consumers are broad or external.
+4. Prefer backward-compatible migrations when consumers are broad or external.
 5. Run `scip-verify` after implementation.
 
 ## Workflow
@@ -20,19 +50,16 @@ Use this skill before changing a public surface. A public surface is a callable,
 ### 1. Identify the surface
 
 ```bash
-scip-query status --capabilities
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
 scip-query surface <module-or-package>
 scip-query outline <file>
 scip-query trace <symbol-or-command>
 scip-query code <symbol-or-command>
+scip-query hierarchy <symbol> --json
 ```
 
-Use `scip-query hierarchy <symbol> --json` for class members or nested methods so you know whether the real surface is the member, class, module, or package.
+This step is complete only when the real surface is named: member, class, module, package, route, schema, command, or config field.
 
-### 2. Find consumers and ownership
+### 2. Find consumers
 
 ```bash
 scip-query refs <symbol>
@@ -42,7 +69,9 @@ scip-query affected <symbol> --json
 scip-query change-surface <file> --json --full
 ```
 
-Record direct consumers separately from transitive consumers. Direct consumers must compile or adapt immediately; transitive consumers define blast radius and regression risk.
+Record direct consumers separately from transitive consumers.
+
+This step is complete only when direct breakage and regression blast radius are known.
 
 ### 3. Find hidden partners
 
@@ -53,18 +82,18 @@ scip-query similar <symbol> --json --full
 scip-query similar-files <file> --json --full
 ```
 
-Use co-change for schema/docs/generator/test partners that do not import each other. Use doc drift when docs mention the surface. Use similarity to find sibling APIs that should remain consistent.
+This step is complete only when docs, generated files, fixtures, sibling APIs, and hand-synchronized partners are accounted for or ruled out.
 
-### 4. Choose the migration shape
+### 4. Choose migration shape
 
 Pick one:
 
-- Compatible extension: add optional behavior without breaking existing callers.
-- Two-step migration: add the new surface, migrate callers, then remove the old surface.
-- Breaking change: update all consumers and docs in one coordinated change.
-- Adapter shim: keep a wrapper only when external consumers or compatibility windows require it.
+- Compatible extension.
+- Two-step migration.
+- Breaking coordinated change.
+- Adapter shim for external consumers or compatibility windows.
 
-Reject speculative parameters or wrappers by running:
+Reject speculative inputs and empty wrappers with:
 
 ```bash
 scip-query unused-params --json --full
@@ -72,80 +101,35 @@ scip-query wrapper-candidates --json --full
 scip-query passthrough-candidates --json --full
 ```
 
-### 5. Build the impact plan
+This step is complete only when the migration shape explains deploy order, rollback, and compatibility risk.
 
-Before editing, write:
+### 5. Build and verify the plan
 
 ```markdown
 Surface:
-- <symbol/file/command/schema>
-
 Consumers:
-- direct: <count and important files>
-- transitive: <count or affected clusters>
-
 Required co-changes:
-- code
-- tests
-- docs
-- generated files
-- config or schema partners
-
 Migration:
-- compatible extension / two-step / breaking / shim
-
 Verification:
 - targeted tests
 - `scip-query diff-impact --json`
-- `scip-query diff-gate --json`
+- invoke `scip-verify`
 - `scip-query doc-drift --json --full` when docs changed
 - `scip-query config-validate` when config changed
 ```
 
-### 6. Verify after editing
+After editing, run routed checks from the shared reference and invoke `scip-verify`.
 
-```bash
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
-scip-query diff-impact --json
-scip-query diff-gate --json
-```
+The work is complete only when direct consumers, docs/config partners, and `scip-verify` have been checked.
 
-Then run routed checks:
-
-```bash
-scip-query unused-params --json --full
-scip-query incomplete-migration --json --full
-scip-query co-change <changed-file> --json --full
-scip-query doc-drift --json --full
-```
-
-Invoke `scip-verify` before declaring the API change ready.
-
-## Report Format
+## Report
 
 ```markdown
 API impact: low/medium/high
-
 Surface changed:
-- <surface>
-
 Consumers:
-- <direct consumers>
-- <transitive blast radius>
-
 Migration plan:
-- <chosen shape and why>
-
 Co-changes:
-- <docs/tests/generated/config partners>
-
 Verification:
-- <commands run and results>
-
 Remaining risk:
-- <external consumers, unavailable capabilities, or accepted compatibility shims>
 ```
-
-Do not call a public-surface change safe until direct consumers, docs/config partners, and `scip-query diff-gate --json` have been checked.