scip-query 0.19.4 → 0.19.6

package/skills/scip-setup/references/language-verification.md

@@ -0,0 +1,61 @@
+# Language-specific verification
+
+Used in bootstrap workflow step 4, and any time an index or capability report
+looks wrong for a specific language.
+
+## TypeScript, JavaScript, and Vue
+
+Require these capability rows to explain their state:
+
+- `scip-typescript` is runnable for SCIP indexing;
+- the detected Tree-sitter TypeScript/JavaScript parser is available for
+  source facts;
+- ts-morph semantic readiness is available for TypeScript;
+- the demand-started service is enabled and status exposes TypeScript
+  semantic and TypeScript index session counters.
+
+For a real multi-project TypeScript monorepo, set
+`indexer.typescript.projectMode: "workspace"`. This makes project/tsconfig
+boundaries the sub-shards, so a changed project and its project-reference,
+workspace-package, or tsconfig-path dependents rebuild while unrelated
+project shards are reused. Use `indexer.typescript.projects` only when
+automatic discovery is too broad; a non-empty list there is authoritative.
+
+Do not enable TypeScript workspace mode for a single-project repository
+merely to seek speed — the normal incremental document producer and
+persistent ts-morph service already reuse unchanged work.
+
+## Rust
+
+Require these distinct facts:
+
+- `rust-analyzer` is runnable and supports `rust-analyzer scip` for indexing;
+- the Tree-sitter Rust grammar is available for source facts;
+- Rust semantic readiness is available for compiler-backed references,
+  callees, signatures, and module/use evidence;
+- status reports the durable Rust transport with worker fallback.
+
+A `stopped` state for the Rust transport (or any demand-started helper) is
+healthy when no semantic request currently needs the clean-idle helper —
+lifecycle state is not the same signal as capability availability.
+
+If `rust-analyzer` is missing and `rustup` is available, `setup` can run
+`rustup component add rust-analyzer`. `SCIP_RUST_SEMANTIC_DURABLE_SESSION=0`
+is an explicit worker-only fallback, not the optimal default — do not set it
+as a default recommendation.
+
+## Other languages
+
+Trust the capability matrix, not a language name. `setup` may install
+supported indexers automatically (for example Python or Go), may provide only
+source facts through a detected Tree-sitter grammar, or may report a manual
+install URL. A missing semantic provider must be reported as unsupported,
+never as a clean semantic analysis.
+
+## Verification commands
+
+```bash
+scip-query status --capabilities
+scip-query reindex --json
+scip-query watch --status --json
+```

package/skills/scip-setup/references/lifecycle-commands.md

@@ -0,0 +1,119 @@
+# Lifecycle commands
+
+`setup` runs most of these internally during a full bootstrap. Reach for one
+directly when only a slice of the footprint needs installing, refreshing, or
+removing — not a full re-bootstrap.
+
+## install-skills
+
+```bash
+scip-query install-skills
+```
+
+When: bundled skills are missing, out of date after a scip-query upgrade, or
+a new agent root (Claude Code, Codex, or a shared agent root) needs the skill
+set that another root already has. Installs `_shared`, `scip-query`,
+`scip-setup`, and the consolidated workflow family into Claude Code, Codex, and
+shared agent roots.
+
+Output to check: the list of skills written or linked per root. Confirm no
+root was silently skipped — an agent root present in the repo but absent from
+the output means that root did not get the skills.
+
+## setup-agent
+
+```bash
+scip-query setup-agent
+```
+
+When: `AGENTS.md`/`CLAUDE.md` has no block pointing agents at the scip-query
+skills and diff gate, or the block is stale relative to the installed
+version. Seeds that guidance block, plus an optional git pre-commit backstop.
+
+Output to check: the diff to `AGENTS.md`/`CLAUDE.md` — confirm the block was
+added or refreshed in place rather than duplicated.
+
+## setup-hooks
+
+```bash
+scip-query setup-hooks
+```
+
+When: project-local Codex or Claude Code lifecycle hooks are missing (never
+installed, or wiped by a settings reset) or need refreshing after a
+scip-query upgrade changed hook contracts.
+
+Output to check: which hook files were written per tool; treat a tool with no
+hook file as not covered.
+
+## setup-ci
+
+```bash
+scip-query setup-ci
+```
+
+When: the user explicitly asks for CI setup — do not run this unless asked.
+Writes a GitHub Actions workflow that runs `scip-query reindex` and
+`diff-gate` on pull requests.
+
+Output to check: the workflow file path written. Tell the user to commit it
+and confirm it triggers on the next PR; this command only writes the file, it
+does not verify the workflow runs.
+
+## check-deps
+
+```bash
+scip-query check-deps
+```
+
+When: you need a fast preflight on whether scip-query and the detected
+language indexers are actually runnable, without running the full `setup`
+sequence — for example, diagnosing a `doctor` complaint about a specific
+indexer, or confirming an environment before a CI run.
+
+Output to check: per-indexer runnable/not-runnable verdicts. A "not runnable"
+verdict here is the reason to go fix that indexer before trusting any index
+built from it.
+
+## augment-sources
+
+```bash
+scip-query augment-sources
+```
+
+When: files are missing from the index even after a clean `reindex`, because
+the upstream SCIP indexer for that language skips them (common for
+non-source files, generated files it doesn't recognize, or files outside its
+project graph). Adds those source files to the SQLite documents table
+directly so source-fact queries can see them.
+
+Output to check: the count and list of files added. If a file you expected is
+still absent, it means the indexer skip reason is not one `augment-sources`
+covers — investigate the specific file rather than re-running the command.
+
+## capability-matrix
+
+```bash
+scip-query capability-matrix
+```
+
+Deprecated alias for `capabilities --matrix`. If you see this in an older
+script or muscle memory, prefer `scip-query capabilities --matrix` directly —
+same output, current name.
+
+## uninstall
+
+```bash
+scip-query uninstall
+```
+
+When: the user wants scip-query's footprint removed from the repo —
+decommissioning, or before trying an alternative tool. Removes
+scip-query-owned skill links, project hooks, and managed agent setup blocks.
+
+Output to check: confirm the removal list covers every artifact `setup`
+reported writing (skills, hooks, agent guidance blocks). Anything `setup`
+wrote that `uninstall` doesn't list as removed needs manual follow-up — for
+example config files (`.scipquery.json`) and the SQLite index are
+intentionally left in place since they may hold data the user still wants;
+tell the user explicitly if they want those gone too.

package/skills/scip-setup/references/per-repo-triage.md

@@ -0,0 +1,24 @@
+# Per-repo triage (once, after setup)
+
+New repos surface standing findings that are intentional. Encode them once so
+every later gate run is precise, instead of re-litigating the same findings
+every time `diff-gate` runs.
+
+1. Sweep initial findings with `health --json` and `diff-gate --json`. For
+   each accepted finding, run `suppress <id> --reason <why>` — reasons are
+   required and audited.
+2. Declare files that legitimately change together in `.scipquery.json`
+   `declaredCouplings`.
+3. List dated snapshot docs (benchmarks, validation ledgers, historical
+   plans/reviews) in `docs.snapshotPaths` so doc checks skip them with a
+   labeled exclusion instead of recurring findings.
+4. Seed `coverageContracts` for every hand-maintained enumeration (policy
+   maps, capability tables, registry lists) so enumeration rot fails the gate
+   the day it happens.
+5. Set a hygiene cadence: run the twin-drift and claim scenarios in
+   `scip-audit` after
+   large refactor campaigns or quarterly. The gate only sees diffs; these
+   lenses see accumulated state.
+
+Complete only when a clean working tree produces a finding-free `diff-gate`
+and every suppression carries a reason a reviewer would accept.

package/skills/scip-verify/SKILL.md

@@ -1,52 +1,52 @@
 ---
 name: scip-verify
-description: Verify finished code, docs, config, refactor, cleanup, setup, React, Vue, or API changes with scip-query. Use before committing or when the user asks whether a change is wired, safe, regression-free, or ready.
+description: Use after finishing a change and before committing: reindex, run the postchecks matching what you edited, diff-gate, and try to refute your own PASS — including verifying that a React or Vue refactor actually achieved the reuse it claimed. Also use to calibrate detector precision once a repo is already set up and its findings look too noisy or too clean. For an existing status claim with no just-finished diff, use scip-audit instead. Distinct from the `review` skill: that one reviews a branch against coding standards and the originating spec; this one runs reindex, routed postchecks and diff-gate on a change you just made.
 commands:
-  - template: 'scip-query doctor'
-    when: 'Prove the workspace: index freshness and dependency readiness.'
-  - template: 'scip-query status --capabilities'
-    when: 'Prove the workspace: which evidence and verification capabilities are available.'
-  - template: 'scip-query diff-impact --json'
-    when: 'Assess the diff: changed symbols and downstream consumers.'
-  - template: 'scip-query diff-gate --json'
-    when: 'Run the gate: the primary blocker for diff-specific risk.'
-  - template: 'scip-query health --baseline'
-    when: 'Check health: compare findings against the committed baseline.'
-  - template: 'scip-query doc-drift --json --full'
-    when: 'Check docs: run when docs, AGENTS.md, or command surfaces changed.'
+  - template: "scip-query doctor"
+    when: "Prove the workspace and configuration are usable before trusting evidence."
+  - template: "scip-query diff-impact --json"
+    when: "Compare changed files, symbols, and affected consumers with the intended diff."
+  - template: "scip-query diff-gate --json --compact"
+    when: "Run the complete finished-diff gate without blind line truncation."
 ---
 
 # scip-verify
 
-Use this skill to verify the actual diff. Verification is the evidence pass that proves the workspace can answer, the index is current, the changed symbols and files match intent, routed postchecks ran, and diff-gate findings are resolved.
+## Purpose
 
-Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+Verification is the evidence pass that proves a finished change is wired,
+safe, and regression-free: the workspace can answer, the index is current,
+the changed symbols and files match intent, every postcheck the edit calls
+for ran, and diff-gate findings are resolved. A PASS is the verdict nobody
+re-checks, so the flow below ends by trying to break it before it's claimed.
+
+Calibration is the companion problem: a detector tuned on one codebase's
+conventions can be precise there and noisy elsewhere, so before any of the
+above output is trusted on a repo, someone has to find out which it is.
+
+Load shared mechanics — command syntax, the evidence contract, diff-gate's
 
 <!-- BEGIN GENERATED SKILL COMMANDS -->
 ## Commands for this skill
 
-| Command | Purpose | When |
-| --- | --- | --- |
-| `scip-query doctor` | Diagnose config, index freshness, dependency readiness, and project capabilities | Prove the workspace: index freshness and dependency readiness. |
-| `scip-query status --capabilities` | Show index status for this project | Prove the workspace: which evidence and verification capabilities are available. |
-| `scip-query diff-impact --json` | Compute changed symbols and downstream consumers from current git diff | Assess the diff: changed symbols and downstream consumers. |
-| `scip-query diff-gate --json` | Gate the current diff: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; exit 1 on blocking findings | Run the gate: the primary blocker for diff-specific risk. |
-| `scip-query health --baseline` | Composite codebase health report with prioritized action list | Check health: compare findings against the committed baseline. |
-| `scip-query doc-drift --json --full` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | Check docs: run when docs, AGENTS.md, or command surfaces changed. |
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query doctor` | Diagnose config, index freshness, dependency readiness, and project capabilities | config, freshness, dependency, and capability diagnostics | `complete` | Prove the workspace and configuration are usable before trusting evidence. |
+| `scip-query diff-impact --json` | Compute changed symbols and downstream consumers from current git diff | changed symbols, downstream consumer identities, and impact paths | `bounded` | Compare changed files, symbols, and affected consumers with the intended diff. |
+| `scip-query diff-gate --json --compact` | Gate the current diff: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; exit 1 on blocking findings | 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` | Run the complete finished-diff gate without blind line truncation. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->
+ten checks, detector-precision tiers — from `_shared`. This skill's own
+shortlist covers `doctor`, `status`, `diff-impact`, `diff-gate`, `health`,
+`doc-drift`, `self-audit`, `suppress`, and `config-validate`.
 
-## Rules
-
-1. Verify environment and index freshness before trusting graph facts.
-2. Treat `scip-query diff-gate --json` as the primary blocker for diff-specific risk.
-3. Run every postcheck that matches the actual edit, not only the check you expected to need.
-4. If `.scipquery.json` or suppressions changed, run `scip-query config-validate`.
-5. Prefer fixing findings. Suppress only intentional design, compatibility shims, framework entry points, or accepted false positives with a specific reason.
-6. A PASS ends scrutiny, so it must survive refutation first: construct the cheapest checks that could still break this diff and run them before claiming PASS. A FAIL needs no refutation — report it with the evidence.
+| Situation | Go to |
+| --- | --- |
+| You just finished editing and need to verify it before committing | Verify a finished change, below |
+| Findings on this repo feel too noisy, too clean, or you're adopting scip-query in a new repo | [`references/calibrate-detectors.md`](references/calibrate-detectors.md) |
 
-## Flow
+## Verify a finished change
 
 ### 1. Prove the workspace
 
@@ -55,7 +55,9 @@ scip-query doctor
 scip-query status --capabilities
 ```
 
-This step is complete only when missing indexers, invalid config, stale indexes, or unavailable relevant capabilities are fixed or reported as blockers.
+Complete only when missing indexers, invalid config, stale indexes, or
+unavailable relevant capabilities are fixed or reported as blockers. Verify
+environment and index freshness before trusting any graph fact that follows.
 
 ### 2. Assess the diff
 
@@ -63,15 +65,40 @@ This step is complete only when missing indexers, invalid config, stale indexes,
 scip-query diff-impact --json
 ```
 
-Compare changed files, changed symbols, and downstream consumers with the intended work. Unexpected blast radius is a finding even if later gates pass.
-
-This step is complete only when the diff shape is understood.
+Compare changed files, changed symbols, and downstream consumers against the
+intended work. An unexpected blast radius is itself a finding even if every
+later gate passes. Complete only when the diff's shape is understood.
 
 ### 3. Run routed postchecks
 
-Use the postcheck table in the shared reference. Run all rows that apply to the change type.
+Run every row that matches what the diff actually did — not only the check
+you expected to need going in:
+
+| Change made | Check |
+| --- | --- |
+| Extracted a helper or abstraction | `scip-query incomplete-migration` |
+| Added a helper, module, component, hook, composable, or adapter | `scip-query recent-duplicates` (and `similar <symbol>`) |
+| Added parameters, options, props, config flags, or option objects | `scip-query unused-params` |
+| Added a wrapper, facade, forwarding layer, alias, or re-export | `scip-query wrapper-candidates`, `passthrough-candidates`, `redundant-reexports` |
+| Added an interface, base class, adapter contract, or type alias | `scip-query stale-abstractions` |
+| Changed schema, config, generated files, public contracts, command descriptors, or docs-backed behavior | `scip-query co-change <file>` and `doc-drift` |
+| Deleted code | `scip-query cleanup-plan --verify` |
+| Changed React components or hooks | the React commands in `_shared` |
+| Changed Vue SFCs or composables | the Vue commands in `_shared` |
+
+Add `--json --full` to any of these when an unbounded machine-readable result
+is needed rather than the bounded default. This table is authoritative — the
+shared reference links here instead of duplicating it, so don't assume a
+different mapping. Complete only when each applicable postcheck has a result
+and every actionable finding is fixed, accepted with evidence, or blocked by
+a named constraint.
+
+If `.scipquery.json` or a suppression file changed as part of the diff, also
+run:
 
-This step is complete only when each applicable postcheck has a result and every actionable finding is fixed, accepted with evidence, or blocked by a named constraint.
+```bash
+scip-query config-validate
+```
 
 ### 4. Run the gate
 
@@ -79,93 +106,119 @@ This step is complete only when each applicable postcheck has a result and every
 scip-query diff-gate --json
 ```
 
-If it reports findings, fix them or record the acceptance reason. If a suppression is needed:
+This is the primary blocker for diff-specific risk: architecture regressions
+plus echo, migration, coordination, doc-drift, unused-param, and new-dead
+candidates, exiting 1 on blocking findings. Fix findings or record the
+acceptance reason. Prefer fixing a real finding over suppressing it — only
+suppress intentional design, compatibility shims, framework entry points, or
+an accepted false positive, and only with a specific reason:
 
 ```bash
 scip-query suppress <id> --reason "<specific reason>"
 ```
 
 `suppress` writes one file per suppression under `.scipquery/suppressions/` —
-commit that file with your change. Suppressing is a real decision, not a
-bypass: every suppression counts against that detector's precision in
-`scip-query effectiveness`, while a rerun against the same resolved comparison
-base earns verified credit. After `HEAD` advances, a clean run replays that
-stored base automatically. Prefer the fix whenever the finding is real.
-
-This step is complete only when `diff-gate` passes or every finding has a durable explanation.
+commit it with the change that produced it. Suppressing is a real decision,
+not a bypass: every suppression counts against that detector's precision in
+`scip-query effectiveness`. A rerun against the same resolved comparison base
+earns verified credit instead; once `HEAD` advances, a clean run replays that
+stored base automatically. Complete only when `diff-gate` passes or every
+finding has a durable explanation.
 
-### 5. Check health, docs, and config when relevant
+### 5. Check health, docs, and generated surfaces when relevant
 
-Run:
+Run
 
 ```bash
 scip-query health --baseline
 ```
 
-when a committed baseline exists. If docs, AGENTS.md, CLAUDE.md, command docs, generated docs, or skill instructions changed, run:
+when a committed baseline exists. If docs, AGENTS.md, CLAUDE.md, command
+docs, generated docs, or skill instructions changed, run
 
 ```bash
 scip-query doc-drift --json --full
 ```
 
-If the repository provides a self-audit command and the change touches generated command surfaces, analyzers, or evidence-labeling behavior, also run:
+and read the returned stale-doc candidates against the diff.
+
+If the change touches generated command surfaces, detectors/analyzers, or
+evidence-labeling behavior, also run
 
 ```bash
 scip-query self-audit
 ```
 
-This step is complete only when changed documentation and config surfaces are checked or explicitly out of scope.
+It scores scip-query's own cheap evidence paths (source-fallback, regex)
+against the best available semantic/compiler oracle on sampled symbols. Read
+whether the surface you just changed still agrees with the oracle at the
+sampled sites before trusting its output elsewhere in this flow — a
+regression here means every downstream postcheck may be reading
+degraded evidence, not just this one command.
 
-### 6. Refute the PASS
+Complete only when changed documentation and config surfaces are checked or
+explicitly declared out of scope.
 
-A PASS is the verdict nobody re-checks — attack it before making it. Construct at least two refutation attempts and run the cheapest check that would expose each. Prefer executed probes (run the consumer's test, invoke the command, feed the edge input) over argued ones. Pick attacks that fit the diff:
+### 6. Refute the PASS
 
-- an unexercised consumer: a caller in `diff-impact` output whose tests did not run — run them, or trace the contract it depends on;
-- an unexercised input: an edge the changed code newly handles or newly rejects — execute it;
-- the intent gap: one case the stated goal implies that the diff does not visibly cover — find where it is handled or show it missing.
+A PASS ends scrutiny, so attack it before making it. Construct at least two
+refutation attempts and run the cheapest check that would expose each. Prefer
+an executed probe — run the consumer's test, invoke the command, feed the
+edge input — over an argued one. Pick attacks that fit the diff:
 
-Record every attempt; an attempt that breaks the diff converts the verdict to FAIL with a finding, and the attempt stays in the record either way.
+- **Unexercised consumer** — take a caller from step 2's `diff-impact` output
+  whose tests did not run, and either run them or trace the contract it
+  depends on.
+- **Unexercised input** — find an edge the changed code newly handles or
+  newly rejects, and execute it.
+- **The intent gap** — find one case the stated goal implies that the diff
+  does not visibly cover, then show where it's handled or show it's missing.
 
-This step is complete only when every refutation attempt has an executed result.
+Record every attempt. An attempt that breaks the diff converts the verdict to
+FAIL with a finding; the attempt stays in the record either way. Complete
+only when every refutation attempt has an executed result.
 
-## Report
+### Report
 
-End with:
+End with this fixed template:
 
 ```markdown
 Verification: PASS/FAIL — <n> postchecks, <m> refutation attempts, <k> broke
 
 Environment:
-
 - doctor:
 - status:
 
 Diff:
-
 - changed files/symbols:
 - unexpected blast radius:
 
 Postchecks:
-
 - <command>: <result>
 
 Gate:
-
 - `scip-query diff-gate --json`: <result>
 
-Health/docs/config:
-
+Health/docs/self-audit:
 - <commands and results>
 
 Refutation attempts:
-
 - R1: <attack> → survived (evidence) | broke (finding)
 
 Remaining risk:
-
 - <accepted findings, unavailable capabilities, or checks not run>
 ```
 
-Do not claim ready-to-ship unless freshness is `fresh` after the final edit, diff-gate is passed or fully explained, and the PASS survived every refutation attempt.
+Do not claim ready-to-ship unless index freshness is `fresh` after the final
+edit, `diff-gate` is passed or fully explained, and the PASS survived every
+refutation attempt.
+
+### Detector reliability for this flow
 
-- `dead`/`new-dead` correctly resolve `import type` consumers, tsconfig `paths` aliases, pnpm/npm/yarn workspace cross-package imports, and Vue `<script setup>` composables. The one residual gap is a same-named symbol reached only through a re-exporting barrel file in a workspace package; that shape self-labels `unconfirmed (cross-package ambiguous-name resolution gap)` in the finding — treat only that label as unconfirmed until `refs` agrees. See the Detector Reliability section in `../_shared/SKILL.md`.
+`dead`/`new-dead` correctly resolve `import type` consumers, tsconfig
+`paths` aliases, pnpm/npm/yarn workspace cross-package imports, and Vue
+`<script setup>` composables — these are not sources of false positives. The
+one residual gap is a same-named symbol reached only through a re-exporting
+barrel file in a workspace package; that shape self-labels `unconfirmed
+(cross-package ambiguous-name resolution gap)` in the finding, and only that
+specific label should be treated as unconfirmed until `refs` agrees.

package/skills/scip-verify/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "SCIP Verify"
-  short_description: "Verify changes with SCIP diff gates"
-  default_prompt: "Use $scip-verify to verify this change with reindexing, routed postchecks, and diff-gate."
+  short_description: "Verify a finished change before it ships"
+  default_prompt: "Use $scip-verify to confirm this change is wired, safe and regression-free before committing it."