scip-query 0.19.4 → 0.19.6

package/skills/_shared/SKILL.md

@@ -1,250 +1,99 @@
 ---
 name: _shared
-description: Shared scip-query reference for bundled skills.
+description: Load only as reference material from within another scip-* workflow skill when that skill's own shortlist is insufficient — never invoke _shared directly as the owning workflow for a task.
 disable-model-invocation: true
 ---
 
-# scip-query Shared Reference
+## Purpose
 
-This is shared reference for scip-query skills. Load it when another skill says to use the shared evidence, lookup, postcheck, or subagent rules.
+`_shared` is the catalog every other scip-* skill draws its command vocabulary and correctness rules from: freshness/lookup mechanics, the full command-family list, detector precision tiers, postcheck rules, the event ledger, and the subagent evidence-boundary contract. It is not a workflow — no task should end with "I invoked `_shared`". Come here mid-task from another skill when that skill's own shortlist runs out.
 
-## Evidence Contract
+A SCIP index is the compiler-derived map of a repository: source files, symbols, references, imports, calls, dependencies. It differs from text search because it records what the language toolchain actually resolved, so a claim backed by it can name definitions and consumers rather than matching strings. A **graph fact** is anything produced from that index — a definition line, a reference site, a caller, a dependency, a reverse dependency, an affected consumer.
 
-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 repository-dead code, file-internal symbols, and implicit-usage signals
-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 drift candidates: unused imports and declared architecture violations; pass --architecture for boundary context
-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 not-implemented # Reachable placeholder stub candidates (throw-stub, TODO+return-default, empty body) — production callers can actually reach these; an unreachable stub is dead's job, not this one's
-scip-query decorative-checkers # Decorative checker candidates: validate*/verify*/check*/assert*/is*/has* callables with no reachable failure exit anywhere in their body
-scip-query test-quality # Test-quality candidates: assertion-free it/test bodies, a skipped-test ledger with git-blame age, and mock-echo tests that assert the same literal they stubbed into a mock
-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] # Count files referencing an exact symbol; top JSON rows include exact symbol identity
-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 architecture # Evaluate project-owned architectural boundaries and dependency rules
-scip-query bottlenecks # Find coupling hubs: high fan-in AND high fan-out
-scip-query deep-chains # Find the longest condensed dependency-component 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: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; 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 work-audit <profile> # Rank exact repeated computations in a profiling JSONL file by measured avoidable time
-scip-query install-skills # Install skills (_shared, scip-query, scip-setup, scip-calibrate, 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-root-cause, 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 as a file under .scipquery/suppressions/ with a required reason
-scip-query effectiveness # Per-check effectiveness from the committed outcome ledger: caught, comparison-verified fixes, suppressed, unverified disappearances, and precision
-scip-query doctor # Diagnose config, index freshness, dependency readiness, and project capabilities
-scip-query setup # Bootstrap this project: enable automatic indexing, 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 in the foreground or manage the per-project background refresh service
-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.
-- **Effectiveness ledger**: every completed diff-gate run, including JSON and hook mode, writes each caught/resolved/suppressed transition to its own committed `.scipquery/events/*.json` file. Independent branches add independent paths instead of editing a shared log; commit the event files with your changes. Legacy `.scipquery/ledger/events.jsonl` records remain readable and migrate on the next gate write. Query the history with `scip-query effectiveness [--since 30d] [--check <check>] [--json]`: per check it reports findings caught, comparison-verified fixed, suppressed, still open, `moved` (rename noise), legacy/non-comparable `unverified` resolutions, precision (verified fixed ÷ verified fixed plus suppressed), and median days-to-fix. A pre-commit rerun reuses the same base directly; after `HEAD` advances, a clean run automatically replays the stored comparison commit. A dirty or unavailable replay leaves the finding pending instead of manufacturing a fix. Standalone detector commands are not outcome-tracked until they expose complete-scan evidence.
-
-## Diff Gate Checks
-
-`diff-gate` recognizes ten 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`), `architecture` (a declared boundary violation absent from the shared baseline), `doc-reference` (uncited or stale doc claim), `unused-params`, `new-dead` (dead code introduced by this diff), and `baseline` (only with `--baseline`: compares all non-architecture health identities against the committed `.scipquery-baseline.json`, distinct from `health --baseline`). The architecture check runs by default only when enforceable architecture rules and a baseline exist; it uses that same file without running the full health suite. 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-backed 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.
+**Match evidence to the claim.** Native search and file reads are valid for literal text, exact local source, and unambiguous local logic (e.g. a helper defined two lines down in the same file is not a resolution claim). Use scip-query whenever the claim depends on compiler-resolved identity or on a relationship set being complete — definitions, references, callers, dependencies, consumers, affected units, public surface. Many scip-query commands return a bounded/capped sample rather than an exhaustive set; say so explicitly rather than treating a bounded result as proof of completeness.
+
+## Triage table
+
+| Need | Where |
+|---|---|
+| Human-oriented command vocabulary and when-to-use notes | `references/command-catalog.md` |
+| Descriptor-owned questions, returned units, and default coverage for every command | `references/agent-contract-catalog.md` |
+| Detector precision tiers, diff-gate's ten checks, root-cause groups, event ledger, effectiveness | `references/detector-precision-and-diffgate.md` |
+| Subagent evidence-boundary contract, dead-code reference-counting status and residual gap | `references/evidence-and-dead-code.md` |
+| The edit-to-postcheck table (which postcheck to run after which kind of edit) | `scip-verify` skill — authoritative, do not duplicate it here |
+
+## Freshness gate
+
+Before trusting any graph fact: run `scip-query status --capabilities`. If freshness reports `fresh`, continue. If it reports `stale`, `missing`, or `unknown`, run `scip-query reindex` first — it indexes the codebase and converts it to SQLite — then re-check status before proceeding.
+
+## Symbol lookup fallback ladder
+
+Look symbols up by partial name, no parentheses: `scip-query code parseConfig`, `scip-query trace loadSettings`. If a lookup is ambiguous or comes back empty:
+1. Retry with a shorter symbol name.
+2. If still unresolved, run `scip-query outline <file>` to get a tree of that file's symbols with line ranges.
+3. If outline doesn't resolve it, run `scip-query trace <name>` (definition plus every reference).
+4. Last resort, once you already know the file and line range: `scip-query code 'path/to/file.ts:START-END'`.
+
+`scip-query files <pattern>` is the step before step 1 when you have a name fragment but no path — feed its result into outline or the lookup ladder. `scip-query stats` gives index statistics; reach for it when validating that a reindex actually populated the index (e.g. during setup/calibration, not mid-exploration).
+
+## Reading a symbol once located
+
+- `scip-query members <symbol>` — every child of a symbol (methods, fields, nested types). Use once `hierarchy` or `by-kind` has identified a class/type, to see its full surface before editing or removing it.
+- `scip-query hierarchy <symbol>` — a method's ancestry chain up to its class and module. Use before editing a method, to understand the containing type's contract.
+- `scip-query by-kind <kind>` — every symbol of a SCIP kind (class, interface, enum, function…). Use after `scip-query kind-counts` (a histogram of kinds in the codebase) narrows down which kind is worth a systematic sweep.
+- `scip-query refs <symbol>` — every file referencing a symbol. This is the strong-signal confirmation step: whenever a dead-code or "is this used" claim needs checking, run `refs` before asserting it.
+
+## Structural surveys before a change
+
+- `scip-query system <module>` — full module map (files, symbols, deps in/out). Use to onboard to an unfamiliar module or produce a module-level briefing.
+- `scip-query surface <module>` — the symbols consumers actually use from a module. Compare against its declared exports to see whether public API can be pruned.
+- `scip-query imports <file>` — what a file imports. Use to audit a file's dependency footprint before moving or refactoring it.
+- `scip-query deps <file>` — internal files this file depends on (upstream blast radius).
+- `scip-query rdeps <file>` — files that depend on this file/module (downstream blast radius: who breaks if it changes).
+
+## Deeper semantics
+
+- `scip-query dataflow <symbol>` — reference-level dataflow: definition sites, usage sites, producers, consumers. Use when debugging or planning a change and location alone (`refs`) isn't enough — you need to know how data moves through the symbol.
+- `scip-query slice <symbol>` — a reference-level program slice, backward (what affects this symbol) or forward (what this symbol affects). Use to scope the minimum code touched by a targeted refactor.
+
+## Dead code and duplication
+
+- `scip-query dead [scope]` — repository-dead code, file-internal symbols, implicit-usage signals. Cross-check any hit with `refs` before deleting; see `references/evidence-and-dead-code.md` for the one residual false-dead gap (ambiguous leaf name reached only through a re-exporting barrel in a workspace package).
+- `scip-query isolated` — completely orphaned symbols with no references at all; the stricter sibling of `dead`, same reference-counting layer, same residual gap caveat.
+- `scip-query similar [symbol] [other]` — heuristic function-similarity candidates from callee fingerprints. Good-with-review signal: read the code before treating a hit as a real duplicate.
+- `scip-query similar-files [file]` — heuristic similar-file candidates from dependency profiles. Use before writing a new file, to check whether a sibling already does the job; review before acting.
+
+## Coupling and architecture health
+
+- `scip-query fan-in [symbol]` — how many files reference an exact symbol. Use to gauge a symbol's criticality/blast-radius before changing its signature.
+- `scip-query fan-out [file]` — how many external symbols a file uses (or the top-fan-out list across the codebase). Use to gauge a file's coupling debt before deciding whether to split it.
+- `scip-query coupling [file1] [file2]` — coupling between two named files, or the top coupled pairs codebase-wide. Use when a specific pair is suspected of hidden coupling, or when scanning for the worst offenders.
+- `scip-query cycles` — circular dependency chains between files. Use when investigating why files resist clean layering or isolated testing.
+- `scip-query bottlenecks` — symbols/files with high fan-in *and* high fan-out (coupling hubs). Use to prioritize a maintainability review.
+- `scip-query architecture` — evaluates project-owned architectural boundaries and dependency rules. Its baseline is what diff-gate's `architecture` check reads from directly (see `references/detector-precision-and-diffgate.md`).
+
+## History
+
+- `scip-query co-change [file]` — files that change together in git history without a dependency edge: hidden-coupling candidates the graph misses. Good-with-review signal. Use before splitting a file to check whether its historical co-change partner also needs updating.
+
+## Governance: config, suppression, effectiveness
+
+1. `scip-query init` — creates `.scipquery.json` for a project. Run once, at bootstrap, before any config-dependent command.
+2. `scip-query config-validate` — validates `.scipquery.json`, including structured suppressions and declared coupling groups. Run after hand-editing either.
+3. `scip-query suppress <id>` — records an accepted finding as a file under `.scipquery/suppressions/` with a required reason, the moment you decide a finding is a false positive or an accepted risk. This is what feeds the "suppressed" count in effectiveness.
+4. `scip-query effectiveness [--since 30d] [--check <check>] [--json]` — per-check history from the committed outcome ledger: findings caught, comparison-verified fixed, suppressed, still open, "moved" (rename noise), legacy/non-comparable "unverified" resolutions, precision (verified-fixed ÷ (verified-fixed + suppressed)), and median days-to-fix. Run this periodically, or the moment diff-gate feels noisy, to see which checks are earning their keep — then 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.
+
+Standalone detector commands (outside diff-gate) are not outcome-tracked in this ledger until they expose complete-scan evidence. A pre-commit rerun of diff-gate reuses the same comparison base directly; after HEAD advances, a clean diff-gate run automatically replays the stored comparison commit. A dirty or unavailable replay leaves the effectiveness finding pending rather than manufacturing a fix result.
+
+## Postcheck
+
+Every implemented change ends with `scip-query status --capabilities` and `scip-query diff-gate --json`. Fix each finding, or record a specific acceptance reason for each one left unresolved (findings marked `(advisory)` never block — treat them as context, not obligations). Do not report success while a diff-gate finding is unexplained. The authoritative table of *which* postcheck to run for *which* kind of edit lives in `scip-verify`; invoke that skill rather than re-deriving it here.
+
+## Subagent evidence boundary
+
+When a subagent gathers scip-query evidence, its prompt must carry these rules verbatim:
+- Use scip-query for any compiler-resolved-identity or completeness claim; native search/file reads are valid only for literal source content and unambiguous local logic (e.g. a helper defined in the same file).
+- The trigger is resolution or completeness, not whether execution crosses a call boundary: asserting what `handler(x)` does without resolving what `handler` is requires scip-query evidence; reading a helper defined two lines down in the same file does not.
+- Cite the evidence source appropriate to each claim, and state plainly when neither source establishes a claim completely.
+
+Reject a subagent's finding if it sources a resolution or completeness claim from text search alone. Do not reject a literal-content claim merely for citing a file read as its evidence.

package/skills/_shared/agents/openai.yaml

@@ -1,4 +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."
+  default_prompt: "Load $_shared only from inside another SCIP skill when its own command shortlist is insufficient."

package/skills/_shared/references/agent-contract-catalog.md

@@ -0,0 +1,105 @@
+# Descriptor-owned command contracts
+
+Use this catalog when choosing between commands or deciding whether a result
+can support a complete claim. Each row is generated from the CLI descriptor
+that also drives help and JSON metadata. “Default coverage” describes the
+normal invocation; the actual JSON result remains authoritative when options,
+scope, runtime capability, or pagination change it.
+
+<!-- BEGIN GENERATED AGENT CONTRACT CATALOG -->
+| Command | Questions it answers | Returns | Default coverage |
+| --- | --- | --- | --- |
+| `scip-query reindex` | Can the repository index be refreshed, and which language shards succeeded? | index generation, shard statuses, reuse diagnostics, and failures | `complete` |
+| `scip-query augment-sources` | Can source files omitted by upstream indexers be added to the index? | added document counts and augmentation status | `complete` |
+| `scip-query augment-vue` | Can Vue SFC references be compiler-resolved and added to the index? | Vue augmentation counts, project, and diagnostics | `complete` |
+| `scip-query stats` | How large and fresh is the current index? | document, symbol, definition, reference, size, and build-time totals | `complete` |
+| `scip-query files <pattern>` | Which indexed files match this text pattern? | matching file paths | `complete` |
+| `scip-query methods <className>` | Which methods belong to this class? | method names and line ranges | `complete` |
+| `scip-query refs <symbol>` | Which files reference this symbol?; Is this symbol used anywhere, or only defined? | referencing file paths; reference line numbers grouped by file | `bounded` |
+| `scip-query trace <symbol>` | Where is this symbol defined, and everywhere is it referenced? | definition sites with source and signature; referencing files with line numbers | `bounded` |
+| `scip-query deps <file>` | Which internal files does this file depend on? | dependency file paths | `complete` |
+| `scip-query rdeps <file>` | Which internal files depend on this file? | reverse-dependency file paths | `complete` |
+| `scip-query system <module>` | What is in this module?; What does this module depend on, and what depends on it? | module file paths; exported symbols with line ranges; internal dependencies; reverse dependencies | `complete` |
+| `scip-query surface <module>` | Which exported symbols do external consumers actually use? | consumer paths and consumed symbol identities | `complete` |
+| `scip-query dead [scope]` | Which symbols have no repository use or only file-internal use? | symbol identities, ranges, liveness classes, and evidence | `bounded` |
+| `scip-query hotspots` | Which symbols are the largest reference choke points? | ranked symbol identities with reference and file counts | `bounded` |
+| `scip-query imports <file>` | Which symbols does this file import? | imported symbol identities and source files | `bounded` |
+| `scip-query imported-by <symbol>` | Which files import this symbol? | importing file paths | `complete` |
+| `scip-query unused-imports <file>` | Which imports in this file are unused? | import symbol identities and source ranges | `bounded` |
+| `scip-query outline <file>` | What symbols and nesting exist in this file? | symbol names, nesting, and line ranges | `complete` |
+| `scip-query members <symbol>` | Which members or nested symbols belong to this symbol? | child symbol identities, kinds, and ranges | `complete` |
+| `scip-query fan-in [symbol]` | How many files reference this symbol, or which symbols have highest fan-in? | exact symbols with referencing-file counts | `bounded` |
+| `scip-query fan-out [file]` | How many external symbols does this file use, or which files have highest fan-out? | files with external-symbol counts | `bounded` |
+| `scip-query coupling [file1] [file2]` | How strongly are these files coupled, or which pairs are most coupled? | file pairs with coupling evidence and scores | `bounded` |
+| `scip-query cycles` | Which file dependency cycles exist? | dependency-cycle file chains | `bounded` |
+| `scip-query architecture` | Does the repository obey its declared architecture boundaries? | boundary coverage and dependency-rule violations | `complete` |
+| `scip-query bottlenecks` | Which files are high-connectivity coupling hubs? | ranked files with fan-in and fan-out counts | `bounded` |
+| `scip-query isolated` | Which symbols are disconnected from the repository reference graph? | isolated symbol identities and files | `bounded` |
+| `scip-query by-kind <kind>` | Which symbols have this SCIP kind? | symbol identities, kinds, files, and ranges | `bounded` |
+| `scip-query kind-counts` | How many indexed symbols exist for each kind? | symbol-kind counts | `complete` |
+| `scip-query deep-chains` | Which dependency chains are deepest and riskiest? | ranked component chains with depth, risk, and recommendation | `bounded` |
+| `scip-query hierarchy <symbol>` | What lexical ownership chain contains this symbol? | ancestor symbol identities and depths | `complete` |
+| `scip-query call-graph <symbol>` | Who calls this symbol and what does it call? | caller and callee symbol identities with files | `bounded` |
+| `scip-query similar [symbol] [other]` | Which callable resembles this one, or how similar are these two? | symbol pairs, similarity scores, and shared evidence | `bounded` |
+| `scip-query similar-files [file]` | Which files have similar callable structure? | file pairs with similarity scores and shared symbols | `bounded` |
+| `scip-query react-component-duplicates [file]` | Which React components appear to duplicate one another? | component pairs with structural similarity evidence | `bounded` |
+| `scip-query react-hook-candidates [file]` | Which repeated React logic could become a custom hook? | component groups and shared hook-shaped behavior | `bounded` |
+| `scip-query react-large-component-pressure [file]` | Which React components have evidence of being too large or overloaded? | component identities with size and responsibility pressure | `bounded` |
+| `scip-query vue-component-duplicates [file]` | Which Vue components appear to duplicate one another? | component pairs with structural similarity evidence | `bounded` |
+| `scip-query vue-composable-candidates [file]` | Which repeated Vue logic could become a composable? | component groups and shared composable-shaped behavior | `bounded` |
+| `scip-query vue-large-view-pressure [file]` | Which Vue views have evidence of being too large or overloaded? | view identities with size and responsibility pressure | `bounded` |
+| `scip-query similar-chains` | Which transitive chains of similar symbols suggest repeated designs? | similarity-connected symbol chains and scores | `bounded` |
+| `scip-query extract-candidates` | Which cohesive code regions are strong extraction candidates? | symbol identities with cohesion, reuse, and extraction evidence | `bounded` |
+| `scip-query locality-candidates [symbol-or-file]` | Which definitions live far from most of their consumers? | symbols, current homes, consumer locality, and suggested homes | `bounded` |
+| `scip-query affected <symbol>` | Which downstream symbols could break if this symbol changes? | affected symbol identities, files, and traversal depths | `bounded` |
+| `scip-query change-surface <file>` | What public surface and consumers make this file risky to change? | defined symbols, external consumer counts, and risk levels | `bounded` |
+| `scip-query cleanup-plan` | What code can be deleted safely, and in what dependency order? | ordered cleanup batches, evidence, and optional verification outcomes | `bounded` |
+| `scip-query cleanup-apply` | Can a compiler-verified cleanup batch be applied to this working tree? | applied files, deletions, verification, and refusal reasons | `bounded` |
+| `scip-query co-change [file]` | Which files repeatedly change together without a declared dependency? | file pairs, co-change counts, confidence, and history context | `bounded` |
+| `scip-query recent-duplicates` | Did recent code reimplement established code? | recent and established symbol pairs with similarity evidence | `bounded` |
+| `scip-query doc-drift [doc]` | Which documentation may be stale relative to changing code? | document paths, coupled code subjects, and history evidence | `bounded` |
+| `scip-query unused-params` | Which trailing parameters are never read by their bodies? | candidate parameters with callable and file identities | `bounded` |
+| `scip-query diff-gate` | Does my current diff introduce something this repo blocks on?; What must I fix or explicitly accept before reporting the work done? | blocking findings with check id, message, and remediation; advisory findings; root-cause groups; changed file and symbol counts; process exit status (1 when blocking findings exist) | `bounded` |
+| `scip-query incomplete-migration` | Did this diff leave a helper extraction only partly migrated? | new helpers and similar unmigrated call sites | `bounded` |
+| `scip-query tla <operation> [spec]` | Does this TLA+ model and code mapping agree, or can the requested model artifact be generated? | checker status, conformance findings, trace coverage, or generated artifact paths | `bounded` |
+| `scip-query plan-context <target>` | What must I know before editing this target?; Who consumes it, and what breaks if I change it?; Has this target historically changed together with anything else? | definitions and references; callers and callees; dataflow producers and consumers; backward and forward slices; affected symbols; change-surface risk; dependencies and reverse dependencies; module files and exports; external surface use; complexity; churn; co-change partners; active suppressions | `bounded` |
+| `scip-query diff-impact` | Which symbols changed in this diff and which downstream consumers are affected? | changed symbols, downstream consumer identities, and impact paths | `bounded` |
+| `scip-query drift [module]` | Where has a module or abstraction drifted across parallel implementations? | drifted symbol families, files, and evidence | `bounded` |
+| `scip-query wrapper-candidates` | Which callables are unnecessary forwarding wrappers? | wrapper identities, targets, and forwarding evidence | `bounded` |
+| `scip-query passthrough-candidates` | Which parameters are passed through layers without local use? | parameter paths across call chains | `bounded` |
+| `scip-query stale-abstractions` | Which abstractions no longer earn their indirection? | abstraction identities with usage, change, and replacement evidence | `bounded` |
+| `scip-query complexity-hotspots` | Which symbols combine high complexity with high change pressure? | ranked symbols with complexity and churn evidence | `bounded` |
+| `scip-query self-audit` | How accurate are the fast evidence paths on a sample? | sample coverage, agreement scores, and disagreements | `sampled` |
+| `scip-query health` | What are the highest-priority verified health problems in this codebase? | health score, findings, priorities, baselines, and coverage notes | `bounded` |
+| `scip-query bench` | How fast are indexing and selected commands under this benchmark matrix? | timings, command outcomes, environment, and optional profiles | `sampled` |
+| `scip-query work-audit <profile>` | Which repeated computations in this profile waste the most measured time? | ranked repeated-work groups, counts, and avoidable duration | `bounded` |
+| `scip-query convergence <symbol1> <symbol2>` | How should these two similar symbols converge? | deprecated alias result for a two-symbol similarity plan | `bounded` |
+| `scip-query code <symbol>` | What is the compiler-resolved definition source for this symbol? | definition identity, source, and line range | `complete` |
+| `scip-query complexity <symbol>` | How structurally complex and connected is this symbol? | LOC, branch, complexity, callee, fan-in, and fan-out counts | `bounded` |
+| `scip-query dataflow <symbol>` | What defines, uses, produces, and consumes this symbol? | definition sites, usage sites, producer symbols, and consumer symbols | `bounded` |
+| `scip-query slice <symbol>` | What transitively affects this symbol, or what does it affect? | connected symbols with relationship and depth | `bounded` |
+| `scip-query install-skills` | Which scip-query skills were installed, updated, skipped, or conflicted? | skill target paths and install outcomes | `complete` |
+| `scip-query setup-hooks` | Were project-local agent hooks installed or removed safely? | hook config targets, changes, skips, and warnings | `complete` |
+| `scip-query check-deps` | Which scip-query and language-indexer dependencies are runnable? | dependency readiness statuses and remediation | `complete` |
+| `scip-query capabilities` | Which evidence and verification capabilities are available here? | capability matrix with availability and reasons | `complete` |
+| `scip-query capability-matrix` | Which evidence and verification capabilities are available here? | deprecated alias of the capability matrix | `complete` |
+| `scip-query redundant-reexports` | Which re-exports add no useful API boundary? | re-export sites, original definitions, and consumer evidence | `bounded` |
+| `scip-query duplicate-bodies` | Which callable bodies are exact duplicates? | callable groups with exact normalized-body identity | `bounded` |
+| `scip-query twin-drift` | Which same-concept twin implementations have drifted? | twin symbol pairs, history, and divergence evidence | `bounded` |
+| `scip-query twin-ab <symbolA> <symbolB>` | How do these two twin implementations differ in structure and behavior? | side-by-side symbol evidence and divergence classification | `complete` |
+| `scip-query not-implemented` | Which callables are placeholders rather than real implementations? | callable identities and placeholder evidence | `bounded` |
+| `scip-query decorative-checkers` | Which validation checks cannot meaningfully fail? | checker identities, call sites, and decorative behavior evidence | `bounded` |
+| `scip-query test-quality` | Which tests have weak assertions or poor production-code reach? | test identities with assertion and reachability evidence | `bounded` |
+| `scip-query similar-signatures` | Which callables have suspiciously similar signatures? | callable pairs with signature similarity evidence | `bounded` |
+| `scip-query init` | Can a starter scip-query configuration be created for this project? | configuration path and creation outcome | `complete` |
+| `scip-query config-validate` | Is this project configuration valid and internally consistent? | validation diagnostics with config paths | `complete` |
+| `scip-query suppress <id>` | Can this accepted finding be recorded with an auditable reason? | suppression identity, path, scope, and expiry | `complete` |
+| `scip-query effectiveness` | Which diff-gate checks catch actionable findings with verified outcomes? | per-check caught, fixed, suppressed, unresolved, and precision counts | `complete` |
+| `scip-query doctor` | Why is scip-query unhealthy or unavailable in this project? | config, freshness, dependency, and capability diagnostics | `complete` |
+| `scip-query setup` | Can scip-query be bootstrapped end to end in this project? | setup step outcomes, files, capabilities, smoke tests, and warnings | `complete` |
+| `scip-query setup-agent` | Can project agent guidance and optional git enforcement be seeded? | written, unchanged, and skipped agent files or hooks | `complete` |
+| `scip-query setup-ci` | Can a CI workflow enforce reindex and diff-gate on pull requests? | workflow path, rendered content, and write outcome | `complete` |
+| `scip-query uninstall` | Which scip-query-owned integrations can be removed without touching user-owned files? | removed, retained, skipped, and dry-run targets | `complete` |
+| `scip-query watch` | What is the watcher doing, or can its background service be started or stopped? | watcher/service state, generation, activity, and errors | `complete` |
+| `scip-query status` | Is the index fresh, complete, and usable for this project? | freshness, generation, language shards, watcher, and optional capabilities | `complete` |
+<!-- END GENERATED AGENT CONTRACT CATALOG -->