scip-query 0.20.0 → 0.21.1

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

@@ -1,119 +0,0 @@
-# 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

@@ -1,24 +0,0 @@
-# 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` and `diff-gate`. 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,229 +0,0 @@
----
-name: scip-verify
-description: Use after finishing a change and before committing: ensure the watcher has produced a fresh index generation, 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 freshness, routed postchecks and diff-gate checks on a change you just made.
-commands:
-  - template: "scip-query doctor"
-    when: "Prove the workspace and configuration are usable before trusting evidence."
-  - template: "scip-query diff-impact"
-    when: "Compare changed files, symbols, and affected consumers with the intended diff."
-  - template: "scip-query diff-gate"
-    when: "Run the complete finished-diff gate without blind line truncation."
----
-
-# scip-verify
-
-## Purpose
-
-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 | 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` | 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` | Runtime-bounded, single-flight gate for 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`.
-
-| 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) |
-
-## Verify a finished change
-
-### 1. Prove the workspace
-
-```bash
-scip-query doctor
-scip-query status --capabilities
-```
-
-Apply `_shared`'s freshness gate here: if the watcher is already refreshing or
-has accepted a refresh request, wait and check once more rather than launching
-a parallel reindex. Use manual `scip-query reindex` only when the index is
-stale, missing, or unknown and the watcher is disabled, unavailable, or failed.
-
-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
-
-```bash
-scip-query diff-impact
-```
-
-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
-
-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 `--full` to any of these when an unbounded 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:
-
-```bash
-scip-query config-validate
-```
-
-### 4. Run the gate
-
-```bash
-scip-query diff-gate
-```
-
-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 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 generated surfaces when relevant
-
-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
-
-```bash
-scip-query doc-drift --full
-```
-
-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
-```
-
-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.
-
-Complete only when changed documentation and config surfaces are checked or
-explicitly declared out of scope.
-
-### 6. Refute the PASS
-
-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:
-
-- **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.
-
-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
-
-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`: <result>
-
-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 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 — 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 +0,0 @@
-interface:
-  display_name: "SCIP Verify"
-  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."

package/skills/scip-verify/references/calibrate-detectors.md

@@ -1,170 +0,0 @@
-# Calibrate detectors
-
-Use this when adopting scip-query in a new or foreign codebase, after major
-detector changes, when a health score or gate output seems too noisy or too
-clean, or before letting `diff-gate` block anyone's work.
-
-## The stance
-
-A detector tuned on one codebase's conventions can be precise there and
-noisy elsewhere. Calibration finds out which, on this repo, and converts
-every noise archetype into either a repo-side knob or an upstream detector
-bug. A health score that hasn't been calibrated is a number, not a fact:
-never present detector output from an uncalibrated repo as findings —
-present it as candidate findings pending classification. A calibrated score
-has to earn trust the same way a checker earns it in the integrity scenario
-of `scip-audit`:
-by being witnessed telling the truth on samples verified by hand.
-
-Run all five stages below. Each has a checkable completion criterion — don't
-move on until it's met.
-
-## Stage 1 — Index and inventory
-
-```bash
-scip-query reindex
-scip-query status --capabilities
-```
-
-Record which languages got which evidence tier (SCIP-indexed vs
-source-fallback vs regex): a detector's expected precision differs per tier,
-and a repo that is 80% fallback-tier must be judged against fallback
-expectations, not SCIP-tier expectations. Note the monorepo shape
-(workspaces, cross-package imports) — historically the single largest
-false-positive source is `dead`/`new-dead` findings on cross-package
-consumers.
-
-Complete only when languages, evidence tiers, and workspace shape are
-written down.
-
-## Stage 2 — Battery sweep
-
-Run the full detector battery and don't react to any of the numbers yet —
-big counts here are sampling frames, not findings:
-
-```bash
-scip-query health
-scip-query dead
-scip-query similar <symbol>
-scip-query twin-drift -s <scope>
-```
-
-Complete only when every detector's finding count is recorded.
-
-## Stage 3 — Retro-gate replay
-
-Replay the gate against the last 15-20 real commits, using a worktree per
-commit — never the user's live tree:
-
-```bash
-scip-query diff-gate --base <commit>
-```
-
-This is the stage that exposes finding WALLS: one hub file or one convention
-mismatch generating dozens of near-identical findings per commit. A finding
-wall is always either a missing repo knob or a detector bug — it is never
-simply "the repo is just bad."
-
-Complete only when per-commit finding counts and every wall are recorded.
-
-## Stage 4 — Sample and classify
-
-This is the actual calibration. For each detector with findings: sample
-about 10 of them (all of them if fewer), read the code at each cited site,
-and classify actionable vs noise.
-
-- Classify from the code, never from the finding text. A finding that
-  sounds plausible and a finding that is true are different things, and the
-  difference is only visible at the cited file and line.
-- For every noise finding, name the archetype (e.g. "type-only import
-  invisible to indexer", "delegation chain flagged as twin", "generic
-  shared helpers saturating similarity"). Archetypes are the deliverable —
-  a noise rate without archetypes cannot be fixed.
-
-Give each detector a verdict: **keep** (precision acceptable), **retune**
-(name the threshold and the value), or **demote to advisory** for this repo.
-
-Complete only when every detector has sampled precision, named archetypes,
-and a verdict.
-
-## Stage 5 — Tune the knobs, file the bugs
-
-Apply repo-side fixes for what belongs to the repo, and file upstream for
-what belongs to the detector:
-
-- `.scipquery.json` suppressions — one per accepted finding, each with a
-  reason. A reasonless suppression is hiding, not tuning.
-- `docs.snapshotPaths` — mark dated/archival docs that must never generate
-  doc-reference findings.
-- Coverage contracts — declare enumerations the gate should police.
-- `commandAnalysisBudget` — cap analysis honestly on very large indexes.
-
-Validate any config change:
-
-```bash
-scip-query config-validate
-```
-
-Detector bugs — noise archetypes no config knob can express — go to the
-tool's followup ledger with the archetype, a concrete example, and the
-sampled rate. Never tune a threshold to hide an archetype; that trades
-visible noise for invisible blindness. File it and live with the noise
-until it's fixed.
-
-Confirm the repair:
-
-```bash
-scip-query diff-gate
-```
-
-run before and after, to check it worked.
-
-Complete only when the stage-3 gate replay re-runs materially quieter and
-every remaining finding class is actionable, suppressed-with-reason, or
-filed upstream.
-
-## Failure modes
-
-Each of these has been observed in a real calibration:
-
-- **Sampling too few.** One good finding does not make a detector precise;
-  one bad finding does not make it noise. Ten samples per detector is the
-  floor.
-- **Classifying from the finding text.** The finding always sounds right —
-  it was generated to. Only the code knows.
-- **Tuning to green.** Raising a threshold until the noise disappears also
-  disappears the real findings. If the archetype is a detector bug, file it
-  and live with the noise rather than tuning it away.
-- **Trusting a clean run.** Zero findings on a detector can mean precision,
-  or it can mean the detector cannot see this repo's conventions at all
-  (wrong import style, unindexed language). Verify at least one known-true
-  positive per major detector — plant one if none exists.
-- **Calibrating the wrong tree.** Use clones or worktrees for anything that
-  mutates during calibration. The target repo is read-only unless its owner
-  said otherwise.
-
-## After calibration
-
-The finding-outcome ledger keeps calibrating automatically. Once the repo
-uses `diff-gate`, per-detector precision is recomputed from real outcomes as
-`detectorPrecision` in `health`. The committed event ledger under
-`.scipquery/events/*.json` makes those outcomes durable and queryable:
-
-```bash
-scip-query effectiveness --since 30d
-```
-
-reports, per check, caught / comparison-verified-fixed / suppressed / open /
-unverified counts, precision, and median days-to-fix, sourced from those
-individual records.
-
-If `HEAD` advances during or after calibration, use a clean worktree so
-scip-query can replay the stored comparison base instead of mistaking an
-empty diff for a fix. Re-run this protocol only after major detector
-upgrades, or when the ledger's precision numbers drift from what was
-measured previously.
-
-Write the calibration report to
-`docs/validation/YYYY-MM-DD-external-calibration-<repo>.md`, shaped like the
-exemplars this protocol was distilled from: battery table, retro-gate walls,
-per-detector verdicts, noise archetypes, caps and deviations.