scip-query 0.19.4 → 0.19.6

package/skills/_shared/references/command-catalog.md

@@ -0,0 +1,118 @@
+# Full command-family vocabulary
+
+Every command the scip-query CLI exposes. Commands marked ★ have a usage scenario in `SKILL.md` — treat this table as the index, not the reasoning. The catalog itself is generated from the CLI's command descriptors, not hand-maintained prose; if a command here looks stale, regenerate rather than hand-edit.
+
+## Index lifecycle
+- `reindex` ★ — indexes the codebase and converts it to SQLite.
+- `augment-sources` — adds source files skipped by upstream SCIP indexers to the documents table.
+- `augment-vue` — adds compiler-resolved Vue SFC references to the index using Volar.
+- `status` ★ — index status for this project (freshness, capabilities).
+- `stats` ★ — index statistics.
+- `watch` — watches in the foreground, or manages the per-project background refresh service.
+
+## Lookup and reading
+- `files <pattern>` ★ — find files matching a pattern.
+- `methods <className>` — list methods of a class with line ranges.
+- `refs <symbol>` ★ — find all files referencing a symbol.
+- `trace <symbol>` ★ — a symbol's definition plus all references.
+- `outline <file>` ★ — tree view of a file's symbols with line ranges.
+- `members <symbol>` ★ — every child of a symbol (methods, fields, nested types).
+- `by-kind <kind>` ★ — find symbols by SCIP kind.
+- `kind-counts` ★ — histogram of symbol kinds in the codebase.
+- `hierarchy <symbol>` ★ — a symbol's ancestry chain, method to class to module.
+- `code <symbol>` ★ — read the source for a symbol, bounded to its definition range.
+- `imports <file>` ★ — what symbols a file imports.
+- `imported-by <symbol>` — which files import this symbol.
+
+## Semantics and structure
+- `dataflow <symbol>` ★ — reference-level dataflow: definitions, usages, producers, consumers.
+- `slice <symbol>` ★ — reference-level program slice, backward or forward.
+- `deps <file>` ★ — files this file depends on (internal).
+- `rdeps <file>` ★ — files that depend on this file/module.
+- `system <module>` ★ — full module map: files, symbols, deps in/out.
+- `surface <module>` ★ — symbols consumers actually use from a module.
+
+## Dead code, duplication, and cleanup heuristics
+- `dead [scope]` ★ — repository-dead code, file-internal symbols, implicit-usage signals.
+- `unused-imports <file>` — imports not referenced in the same file.
+- `isolated` ★ — completely orphaned symbols with no references at all.
+- `similar [symbol] [other]` ★ — heuristic function similarity from callee fingerprints.
+- `similar-files [file]` ★ — heuristic similar-file candidates from dependency profiles.
+- `similar-chains` — heuristic similar-chain candidates from dependency flows.
+- `extract-candidates` — heuristic extraction candidates from isolated callee clusters.
+- `locality-candidates [symbol-or-file]` — directory-locality/ancestry candidates from consumer ownership.
+- `cleanup-plan` — ordered, batched deletion plan: graph-fact dead code plus cascade candidates it unlocks.
+- `cleanup-apply` — applies a compiler-verified cleanup-plan batch to the working tree.
+- `recent-duplicates` — directional duplicate candidates: recent code re-implementing established code.
+- `doc-drift [doc]` — stale-doc candidates: cited code, or co-changed code that kept changing after the doc stopped.
+- `unused-params` — speculative-generality candidates: trailing parameters no body uses (TS/JS).
+- `drift [module]` — unused imports and declared architecture violations; pass `--architecture` for boundary context.
+- `wrapper-candidates` — heuristic wrapper candidates called by one consumer. **Exploration only** — see precision tiers.
+- `passthrough-candidates` — heuristic passthrough candidates that forward to one callee.
+- `stale-abstractions` — heuristic candidates with 0-1 consumers. **Exploration only** — see precision tiers.
+- `complexity-hotspots` — heuristic complexity hotspots from LOC × fan-in × fan-out. Strong signal, ~90% precision.
+- `convergence <s1> <s2>` — **deprecated**, alias for `similar <s1> <s2> --plan`; prefer the latter.
+- `redundant-reexports` — barrel re-exports nobody imports through.
+- `duplicate-bodies` — exact duplicate small-body candidates across files.
+- `twin-drift` — same-name (or near-name) functions across files with diverged bodies.
+- `twin-ab <symbolA> <symbolB>` — generates a behavioral A/B vitest scaffold comparing two same-concept twins; a ready-to-fill file, not an auto-executor.
+- `not-implemented` — reachable placeholder stubs (throw-stub, TODO+return-default, empty body) with a real production caller; an unreachable stub belongs to `dead` instead.
+- `decorative-checkers` — validate*/verify*/check*/assert*/is*/has* callables with no reachable failure exit.
+- `test-quality` — assertion-free test bodies, a skipped-test ledger with git-blame age, mock-echo tests.
+- `similar-signatures` — functions with near-identical type signatures.
+
+## React / Vue heuristics
+- `react-component-duplicates [file]` — duplicated JSX structure candidates (tags, props, events, bindings).
+- `react-hook-candidates [file]` — hook-extraction candidates from shared state/effects/requests/handlers.
+- `react-large-component-pressure [file]` — large-component-pressure candidates from lines, JSX structure, hooks.
+- `vue-component-duplicates [file]` — duplicated template structure candidates (tags, bindings, slots, directives).
+- `vue-composable-candidates [file]` — composable-extraction candidates from shared state/effects/requests/bindings.
+- `vue-large-view-pressure [file]` — large-view-pressure candidates from template/script/style/external line counts.
+
+## Coupling, architecture, impact
+- `hotspots` — most-referenced symbols in the codebase (choke points).
+- `fan-in [symbol]` ★ — files referencing an exact symbol; top JSON rows include exact symbol identity.
+- `fan-out [file]` ★ — external symbols a file uses, or top fan-out codebase-wide.
+- `coupling [file1] [file2]` ★ — coupling between two files, or top coupled pairs codebase-wide.
+- `cycles` ★ — circular dependency chains between files.
+- `architecture` ★ — evaluates project-owned architectural boundaries and dependency rules.
+- `bottlenecks` ★ — high fan-in AND high fan-out symbols/files.
+- `deep-chains` — longest condensed dependency-component chains.
+- `call-graph <symbol>` — incoming callers and outgoing callees for a symbol.
+- `affected <symbol>` — transitive closure of symbols that could break if this symbol changes.
+- `change-surface <file>` — pre-change briefing: exports, consumers, blast-radius risk.
+- `co-change [file]` ★ — files that change together in git history without a dependency edge.
+
+## Diff, migration, formal modeling
+- `diff-gate` — gates the current diff; see `detector-precision-and-diffgate.md` for its ten checks.
+- `incomplete-migration` — partially-completed extraction candidates left un-migrated at similar sites.
+- `diff-impact` — changed symbols and downstream consumers from the current git diff.
+- `tla <operation> [spec]` — TLA+ workflow: verify a model/mapping contract, scaffold a draft model, generate a trace recorder, or check a recorded trace against the next-state relation.
+- `plan-context <target>` — pre-edit planning context for a symbol, file, or module.
+
+## Health, complexity, performance
+- `self-audit` — scores cheap evidence paths against the best available semantic/source oracle on sampled symbols.
+- `health` — composite codebase health report with a prioritized action list.
+- `complexity <symbol>` — per-symbol complexity: branches, cyclomatic estimate, fan-in/out, callees.
+- `bench` — benchmarks indexing and command runtimes for the repository.
+- `work-audit <profile>` — ranks exact repeated computations in a profiling JSONL file by measured avoidable time.
+
+## Setup, config, governance
+- `install-skills` — installs the nine bundled router, workflow, and shared-reference skills into Claude Code, Codex, and shared agent roots.
+- `setup-hooks` — installs or refreshes project-local Codex and Claude Code lifecycle hooks.
+- `check-deps` — checks whether scip-query and detected language indexers are actually runnable.
+- `capabilities` — reports which evidence/verification capabilities are available in this project.
+- `capability-matrix` — **deprecated**, alias for `capabilities --matrix`; prefer the latter.
+- `init` ★ — creates `.scipquery.json` for this project.
+- `config-validate` ★ — validates `.scipquery.json`, including suppressions and declared coupling groups.
+- `suppress <id>` ★ — records an accepted finding under `.scipquery/suppressions/` with a required reason.
+- `effectiveness` ★ — per-check effectiveness from the committed outcome ledger.
+- `doctor` — diagnoses config, index freshness, dependency readiness, project capabilities.
+- `setup` — bootstraps a project: automatic indexing, agent skills, index refresh, capability check, health report.
+- `setup-agent` — seeds an AGENTS.md/CLAUDE.md block pointing agents at the scip-query skills and diff gate, plus an optional git pre-commit backstop.
+- `setup-ci` — writes a GitHub Actions workflow running `reindex` and `diff-gate` on pull requests.
+- `uninstall` — removes scip-query-owned skill links, project hooks, and managed agent setup blocks.
+
+## General rule on coverage
+
+Each command's returned set is either complete (exhaustive) or bounded (capped/sampled). Where that isn't stated explicitly for a given command, assume bounded and say so before treating the result as proof of completeness — a bounded result narrows, it does not exonerate.

package/skills/_shared/references/detector-precision-and-diffgate.md

@@ -0,0 +1,59 @@
+# Detector precision, diff-gate, and the event ledger
+
+## Weight findings by measured precision, not volume
+
+Detector precision was calibrated against two external production repos on 2026-07-01 (`docs/validation/2026-07-01-external-calibration-*.md`). Use that calibration to decide how much a finding is worth acting on alone versus needing corroboration.
+
+**Strong signal — act on directly:**
+- `complexity-hotspots` (~90% precision)
+- `recent-duplicates` (~75% precision)
+- Graph facts from `refs`, `trace`, `deps`
+- Compiler-verified `cleanup-plan --verify` output
+
+**Good with review — read the cited code before acting:**
+- `duplicate-bodies`, `similar`, `co-change`, `doc-drift`, `twin-drift` (post-retune defaults)
+
+**Exploration only — near-zero precision on codebases with intentional layering or ambient types:**
+- `wrapper-candidates`, `stale-abstractions`, `drift --patterns`
+
+Never file a finding from an exploration-only detector without reading the cited code first. `convergence <s1> <s2>` and `capability-matrix` are deprecated aliases (`similar <s1> <s2> --plan` and `capabilities --matrix` respectively) — prefer the modern form.
+
+## diff-gate
+
+`diff-gate` gates the current diff for architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates, and exits 1 on blocking findings. It recognizes ten checks, any of which can be skipped individually with `--skip <check>`:
+
+| Check | Flags |
+|---|---|
+| `echo` | recent-duplicate-style echoes in the diff |
+| `incomplete-migration` | partially-completed extractions left in the diff |
+| `co-change-partner` | a missing historically-paired file |
+| `twin-partner` | an unedited same-name twin — **advisory**, never blocks |
+| `coverage-contract` | a configured `coverageContracts` enumeration drifted from ground truth (see `scip-setup`) |
+| `architecture` | a declared boundary violation absent from the shared baseline |
+| `doc-reference` | an uncited or stale doc claim |
+| `unused-params` | trailing parameters no body uses |
+| `new-dead` | dead code introduced by this diff |
+| `baseline` | only active with `--baseline`; compares all non-architecture health identities against `.scipquery-baseline.json` — distinct from `health --baseline` |
+
+The `architecture` check runs by default only when enforceable architecture rules and a baseline exist, and it reads that baseline file directly without running the full health suite.
+
+**Reading grouped output:** findings print grouped under a `Root-cause groups (N):` header before the flat list. A root-cause group's remediation usually clears every finding under it. The same remediation may repeat afterward in the flat list below the groups — that repetition is expected, not a separate issue.
+
+**actionTier** on baseline-backed findings tells you how directly to act:
+- `direct` — act on this finding alone.
+- `signal` — corroborating evidence; read before acting.
+- `support` — context only.
+
+Findings marked `(advisory)` never block; treat them as context, not obligations. Fix every finding, or record a specific acceptance reason for each one left unresolved — never report success while a finding is unexplained.
+
+## Event 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 should add independent event files rather than editing a shared log, and commit them with the corresponding change. Legacy `.scipquery/ledger/events.jsonl` records remain readable and migrate automatically on the next gate write.
+
+## Effectiveness
+
+`scip-query effectiveness [--since 30d] [--check <check>] [--json]` reports, per check: 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.
+
+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 instead of manufacturing a fix result. Standalone detector commands (outside diff-gate) are not outcome-tracked in this ledger until they expose complete-scan evidence.
+
+When `diff-gate --hook` reports that a check is rarely acted on in this repo: tune that check's config, suppress the standing findings with reasons, or consciously accept the noise. Do not let unresolved findings accumulate as wallpaper.

package/skills/_shared/references/evidence-and-dead-code.md

@@ -0,0 +1,25 @@
+# Subagent evidence boundary and dead-code resolution status
+
+## Subagent evidence boundary
+
+When a subagent is used to gather scip-query evidence, its prompt must include these rules verbatim:
+- Use scip-query for compiler-resolved identity and completeness claims.
+- Native search/file reads are valid for literal source content and local logic, including an unambiguous helper visible in the same file.
+- Cite the evidence source appropriate to each claim.
+- State explicitly when neither source establishes a claim completely.
+
+The trigger for requiring scip-query evidence is **resolution or completeness, not whether execution crosses a call boundary.** Asserting what `handler(x)` does without resolving what `handler` is constitutes a resolution claim and requires scip-query evidence. Reading a helper defined two lines down in the same file is not a resolution claim and does not require it.
+
+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.
+
+## Dead-code reference-counting status (as of the 2026-07-02 remediation, `docs/plans/2026-07-02-followups.md` items 1-3)
+
+The shared reference-counting layer used by `dead`, `isolated`, `new-dead`, and `stale-abstractions` correctly resolves as consumers:
+- import type-only consumers, including tsconfig paths-aliased specifiers;
+- pnpm/npm/yarn workspace cross-package consumers, including unbuilt `dist/` exports-map consumers.
+
+Vue `<script setup>` composable consumers were already correctly resolved before this remediation — verified live, no code change needed.
+
+**One 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 be misattributed as dead. For that case, `new-dead` labels the finding `unconfirmed (cross-package ambiguous-name resolution gap)` with evidence `heuristic` and lowered confidence, instead of asserting dead — treat it as "verify manually," not fact.
+
+Outside that one residual gap, dead-code findings in this class are normal graph-fact dead claims: confirm with `refs` when in doubt, same as any other finding.

package/skills/scip-audit/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: scip-audit
+description: Use to find and confirm problems WITHOUT editing: is this implementation real (decorative checkers, not-implemented, lying metrics), is a status word derived or merely asserted, are cleanup findings worth acting on, has a same-name twin silently drifted, have the living docs (AGENTS.md, standards, command docs) drifted from the code, and are there hidden policies, scattered concepts, accidental variation or weak boundaries — including React/Vue component and directory-locality pressure. Proactive: needs no reported symptom. Hand confirmed findings to scip-improve. Distinct from `complexity-cleanup` and `principal-maintainability-review`: those reason about a specific symbol's complexity or a reviewer's judgement; this one runs detectors across the repo and ranks confirmed findings by evidence.
+commands:
+  - template: "scip-query health --json"
+    when: "Orient to the repository-wide finding inventory before confirming candidates."
+  - template: "scip-query decorative-checkers --json --full"
+    when: "Audit whether validation-shaped code has a reachable failure exit."
+  - template: "scip-query doc-drift --json --full"
+    when: "Find current-guidance documents whose cited or coupled code moved."
+---
+
+# scip-audit
+
+Read-only evidence audits. Every audit here classifies something —
+real-vs-decorative, derived-vs-asserted, confirmed-vs-noise, drifted-vs-stable
+— and ends in a ranked, evidenced verdict. None of them edit code or docs.
+When a finding needs a fix, hand it to `scip-improve`; do not apply it here.
+
+Load shared mechanics (evidence freshness, lookup, the full command
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query health --json` | Composite codebase health report with prioritized action list | health score, findings, priorities, baselines, and coverage notes | `bounded` | Orient to the repository-wide finding inventory before confirming candidates. |
+| `scip-query decorative-checkers --json --full` | Decorative checker candidates: validate*/verify*/check*/assert*/is*/has* callables with no reachable failure exit anywhere in their body | checker identities, call sites, and decorative behavior evidence | `bounded` | Audit whether validation-shaped code has a reachable failure exit. |
+| `scip-query doc-drift --json --full` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | document paths, coupled code subjects, and history evidence | `bounded` | Find current-guidance documents whose cited or coupled code moved. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+catalogue) from `../_shared/SKILL.md` — each reference file below carries its
+own shortlist first and only defers to `_shared` when that shortlist runs
+out. Before trusting any graph fact, confirm the index is fresh with
+`scip-query status --capabilities` (reindex if `stale`/`missing`/`unknown`).
+
+## Triage
+
+| Situation | Open | Core commands |
+|---|---|---|
+| A checker/verifier/metric/feature might be decorative, half-built, or a fallback might be masking a dead primary path | [`references/integrity.md`](references/integrity.md) | `decorative-checkers`, `not-implemented`, `twin-ab`, `test-quality`, `refs`, `code`, `call-graph` |
+| A status word ("available", "verified", "safe", "PASS", "complete") needs classifying as derived, hedged, or asserted | [`references/claims.md`](references/claims.md) | `files`, `refs`, `code`, `trace`, `capabilities` |
+| Turning a health report, de-bloat report, AI-residue sweep, or raw detector output into a confirmed cleanup queue | [`references/cleanup.md`](references/cleanup.md) | `health`, `cleanup-plan`, `duplicate-bodies`, `recent-duplicates`, `incomplete-migration`, `doc-drift`, `unused-params`, `passthrough-candidates`, `dead`, `isolated`, `cycles`, `co-change` |
+| Same-name or near-name functions across files whose bodies have silently diverged | [`references/twin-drift.md`](references/twin-drift.md) | `twin-drift`, `duplicate-bodies`, `code`, `refs`, `diff-gate` |
+| Hidden policy, scattered concepts, accidental variation, weak boundaries — general structural/maintainability pressure | [`references/maintainability.md`](references/maintainability.md) | `stats`, `system`, `surface`, `change-surface`, `affected`, `drift`, `health`, `similar*`, `extract-candidates`, `wrapper-candidates`, `stale-abstractions`, `cycles` |
+| React or Vue component/hook/composable duplication, or large-component/view pressure | [`references/frontend.md`](references/frontend.md) | `react-component-duplicates`, `react-hook-candidates`, `react-large-component-pressure`, `vue-component-duplicates`, `vue-composable-candidates`, `vue-large-view-pressure`, `augment-vue`, `recent-duplicates`, `similar`, `health` |
+| Folder structure, ownership boundaries, locality config, a messy or AI-generated layout, safe move slices | [`references/directory.md`](references/directory.md) | `system`, `locality-candidates`, `similar-files`, `cycles`, `architecture`, `drift`, `co-change`, `config-validate`, `diff-gate`, `health` |
+
+Rows are not exclusive. A "does this actually work" investigation that turns
+up structural mess routes that mess to `references/maintainability.md`
+instead of forcing it into the integrity verdict — real-but-messy is a
+different failure mode than fake-but-green. A twin-drift finding that
+surfaces on your own diff (via `diff-gate`) is a live instance of that defect
+class, not just a gate finding — open `references/twin-drift.md`.
+
+## Cross-cutting rules
+
+- **Classify, don't just list.** Every audit in this skill assigns each item
+  in scope to exactly one label from its taxonomy (real/decorative,
+  derived/hedged/asserted, confirmed/intentional/false-positive/blocked,
+  intentional-variation/drifted-policy/one-sided-fix, mature/emerging/
+  accidental). A count that doesn't sum to the scope size is an unfinished
+  audit.
+- **Ground every claim in evidence**, not opinion or a variable's name — a
+  variable called `verified` that nothing ever checked is still asserted.
+  Name concrete files/symbols before naming a smell.
+- **Preserve essential variation.** Difference that reflects real behavior,
+  domain facts, runtime constraints, or external contracts is not a defect;
+  consolidating it away is a false abstraction. Any merge/consolidate
+  recommendation must carry the single trait that makes the cited sites one
+  concept — if that trait can't be stated, they aren't one concept.
+- **A clean run is itself a claim.** A suspect scope that produces zero
+  findings needs a stated reason the suspicion was wrong, not silence.
+- **This skill never edits.** Findings, evidence, and a fix direction are the
+  deliverable; route action to `scip-improve`.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Audit"
+  short_description: "Find and confirm real problems without editing"
+  default_prompt: "Use $scip-audit to proactively find and confirm real problems in this codebase without changing any code."

package/skills/scip-audit/references/claims.md

@@ -0,0 +1,98 @@
+# Claims: derived, hedged, or asserted?
+
+Classify whether an "available", "verified", "safe", "PASS", or "complete"
+status word is derived from a real check, hedged as a candidate, or merely
+asserted without being probed.
+
+Command shortlist: `files <pattern>` (inventory), `refs <symbol>` /
+`code <symbol>` / `trace <symbol>` (classify), `capabilities --matrix --json`
+(spot-check against a known-good derived surface).
+
+## Taxonomy
+
+- **Derived** — the producer computes the value from a real probe, scan, or
+  computation (a compiler run, a runtime capability probe, a graph
+  traversal).
+- **Hedged** — the code or its label already says it is a candidate,
+  heuristic, or unverified. Hedged is not a finding — the label already
+  discloses the uncertainty.
+- **Asserted** — the value is a constant, a hardcoded table entry, or a
+  string literal presented with the same confidence as a derived value but
+  backed by nothing the code actually checked at that call site.
+
+Asserted status words that are agent-facing and trust-bearing — an agent
+would route a decision ("use this evidence", "skip this check", "delete
+this") based on the word — are the highest-severity class this audit exists
+to find.
+
+Ground every claim in the producing function's source, not its label or
+variable name alone: a variable named `verified` that is never checked
+against a real result is still asserted. Every status word in scope gets
+exactly one of the three labels.
+
+## Severity rubric
+
+Asserted + agent-facing + trust-bearing = high. Asserted + internal-only or
+low-consequence = low. Hedged is not a finding.
+
+A status that used to be asserted and now calls a real probe is fixed — say
+so and move on, do not re-report it.
+
+## Step 1 — Inventory
+
+Grep the target scope (a file, module, or command family) for user-visible
+or JSON-facing status words (`available`, `unavailable`, `partial`,
+`verified`, `safe`, `PASS`, `FAIL`, `complete`, `derived`, `asserted`),
+noting the file:line and the renderer or JSON field surfacing each hit. Use
+`scip-query files <target-file-or-pattern>` to locate the renderer or
+status-producing module for a claim.
+
+**Complete when:** every status-bearing string or field in scope is listed
+with its surface (human output, `--json` field, or both).
+
+## Step 2 — Classify
+
+For each status word's producing function, run `refs`, `code`, and `trace`,
+read the function body, and classify it as derived (computed from a probe,
+scan, spawn result, file check, or graph query performed at or near that
+call site), hedged, or asserted.
+
+**Complete when:** every producer has one of the three labels with the one
+line of source evidence that justifies it.
+
+Use `scip-query capabilities --matrix --json` as a spot-check: an
+already-known example of a fixed derived-status surface, useful for
+calibrating what "derived" looks like in this codebase before judging
+ambiguous cases.
+
+## Step 3 — File and fix
+
+File findings as a table, not prose. Finding format:
+
+- **Claim** — the status word and where it appears.
+- **Producer** — file:line, function name.
+- **Classification** — asserted.
+- **Severity** — high or low (per the rubric above).
+- **Fix** — probe it (name the real check to add), generate it (derive from
+  a registry/config that is itself kept honest), or soften the language
+  (hedge the label to match what is actually known).
+
+**Complete when:** every asserted status in scope has a filed finding with a
+fix direction, and every derived/hedged status is confirmed correct (not
+silently asserted behind a computed-looking name).
+
+## Report
+
+Write the audit report under `docs/scip-query/` unless the user asked only
+for a conversational answer. Template:
+
+- Scope
+- Status words inventoried: N
+- Classified: `<d>` derived / `<h>` hedged / `<a>` asserted — must sum to N;
+  a gap is an unfinished audit
+- Claim table: Claim, Producer, Classification, Fix
+- "Fixed since last audit" — claims now derived that were previously
+  reported asserted
+
+The audit is complete only when every status word in scope is classified and
+every asserted, trust-bearing claim has a filed finding.

package/skills/scip-audit/references/cleanup.md

@@ -0,0 +1,101 @@
+# Cleanup: raw signal to confirmed queue
+
+Turn raw scip-query cleanup signals into a confirmed cleanup queue. Use for
+health reports, de-bloat reports, recent AI-residue audits, score-framed
+cleanup queues, confirming raw findings, or preparing a cleanup plan.
+
+This audit never edits application code — it only audits and classifies
+signals; applying fixes is `scip-improve`'s job.
+
+Three common modes, same underlying workflow:
+
+- **Whole-repo audit** — rank all cleanup signals across the codebase.
+- **Recent-AI-residue** — focus specifically on echoes, twins, incomplete
+  migrations, speculative params, stale agent-facing docs, and hidden
+  couplings.
+- **Score-framed** — explain the health score's deductions and identify the
+  safest first cleanup batch.
+
+## Step 1 — Establish evidence
+
+Before any sweeping begins, run `scip-query doctor`, `scip-query status
+--capabilities`, `scip-query health --json`, `scip-query capabilities
+--json`, and `scip-query config-validate --json`.
+
+**Complete when:** unavailable capabilities are explicitly recorded as
+unavailable, not silently skipped.
+
+## Step 2 — Sweep signals
+
+Run every relevant detector class or explicitly record why it is
+unavailable — never silently omit a class.
+
+Core sweep set:
+
+```
+scip-query cleanup-plan --verify --json          # compiler-verified batched deletion plan
+scip-query duplicate-bodies --json --full        # exact duplicate small-body candidates
+scip-query recent-duplicates --json --full       # recent code re-implementing established code
+scip-query incomplete-migration --json --full    # partially-completed extractions
+scip-query unused-params --json --full
+scip-query passthrough-candidates --json --full
+scip-query dead --json --full
+scip-query isolated --json --full
+scip-query cycles
+scip-query co-change --json --full               # hidden file-level coupling from git history
+scip-query doc-drift --json --full                # docs whose referenced/co-changed code kept moving
+```
+
+`scip-query health --json` establishes the composite score and prioritized
+action list; `scip-query cleanup-plan --verify --json` combines graph-fact
+dead code with the cascade candidates it unlocks. `scip-query doc-drift
+--json --full` finds stale-doc candidates: code a doc references, or
+co-changed with, that kept changing after the doc stopped — run it whenever
+the audit is about living-doc drift, not just code cleanup.
+
+For frontend repos, add the React/Vue duplicate, hook/composable, and
+large-component/view detector commands (see `references/frontend.md`) to the
+sweep.
+
+**Optional deep dives**, run only after the main sweep is exhausted:
+`scip-query stale-abstractions --json --full` and `scip-query
+wrapper-candidates --json --full` have near-zero precision on codebases with
+intentional layering or ambient types — treat every hit as a lead to
+confirm, never a finding on its own.
+
+## Step 3 — Confirm each candidate
+
+Classify every cleanup candidate as exactly one of: **confirmed fix
+target**, **intentional design**, **false positive**, or **blocked**.
+
+To confirm a high-priority candidate, inspect source and graph evidence with
+`scip-query code`, `scip-query refs`, `scip-query fan-in`, `scip-query
+fan-out`, `scip-query affected --json`, `scip-query change-surface --json
+--full`, `scip-query similar --plan`, and `scip-query co-change --json
+--full`.
+
+Because a deletion is this audit's scrutiny-ending verdict, a candidate
+classified "confirmed fix target" that deletes code must survive refutation
+checks before being finalized:
+
+1. Run `rg` for the symbol name as a plain string to catch dynamic dispatch,
+   config keys, serialized references, and CLI/doc text that graph-based
+   detectors cannot see.
+2. Check for the cross-package barrel re-export gap — the one blind spot
+   `dead` self-labels as "unconfirmed."
+
+Record `refutation: survived — <checks run>` on a confirmed-deletion entry
+once the blind-spot checks pass, or reclassify the entry if they don't;
+either way the note must be recorded.
+
+## Report
+
+Final report must include: health score, classification counts
+(confirmed/intentional/false positive/blocked — must cover every collected
+signal, none left uncounted), confirmed items with evidence and first safe
+action, unconfirmed signals with evidence still needed, unavailable/blocked
+checks with reasons, and a recommended first cleanup batch with why it's
+safe now.
+
+A run is complete only when each collected signal is classified and the
+next action is visible.