scip-query 0.10.2 → 0.10.4

package/skills/concrete-plan/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: concrete-plan
 description: Build concrete, checklist-driven implementation plans using scip-query for every code reference. Plans are stress-tested against 11 engineering principles before shipping.
-allowed-tools: [Bash, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
-keywords: [plan, design, architecture, implementation, checklist, blueprint, proposal, rfc, spec]
 ---
 
 # Concrete Implementation Planning
@@ -114,7 +112,7 @@ This skill deliberately excludes `Grep` and `Read` from its allowed tools. This
 | Reverse dependencies | `scip-query rdeps <file>` |
 | **Full transitive blast radius** | `scip-query affected <symbol>` |
 | **Pre-change risk briefing** | `scip-query change-surface <file>` |
-| **Git diff impact analysis** | `scip-query diff-impact` |
+| **Git diff impact analysis** | `scip-query diff-impact --json` |
 | **Complexity analysis** | `scip-query complexity <symbol>` (branches, cyclomatic, fan-in/out) |
 | **Dataflow: what feeds in/out** | `scip-query dataflow <symbol>` (producers, consumers, usage sites) |
 | **Backward slice (what affects this)** | `scip-query slice <symbol>` |
@@ -296,7 +294,7 @@ After stress-testing is complete:
 3. **Fix drift**: Update any stale references.
 4. **Check execution order**: No phase depends on a later phase. No step within a phase depends on a later step.
 5. **Check validation coverage**: Every behavior-changing step should have a corresponding validation step. Flag gaps in tests, manual checks, or runtime verification.
-6. **Run diff-impact**: `scip-query diff-impact` to verify the blast radius matches what the plan predicted.
+6. **Run diff-impact**: `scip-query diff-impact --json` to verify the blast radius matches what the plan predicted.
 
 ---
 
@@ -327,7 +325,7 @@ Dependencies & Impact:
 - `scip-query rdeps <file>` — files that depend on this file
 - `scip-query affected <symbol>` — transitive closure of breakage
 - `scip-query change-surface <file>` — pre-change risk briefing
-- `scip-query diff-impact` — git diff impact analysis
+- `scip-query diff-impact --json` — git diff impact analysis
 
 Analysis:
 - `scip-query complexity <symbol>` — branches, cyclomatic estimate, fan-in/out

package/skills/concrete-plan/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Concrete Plan"
+  short_description: "SCIP-grounded implementation plans"
+  default_prompt: "Use $concrete-plan to create a SCIP-grounded implementation plan for this change."

package/skills/scip-adoption/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: scip-adoption
+description: Adopt scip-query in a repository from first run through verified local readiness. Use when the user wants to install, bootstrap, onboard, set up, refresh, or roll out scip-query in a project, including skills, indexers, local capabilities, health dossier, and post-setup cleanup handoff.
+---
+
+# SCIP Adoption
+
+Use this skill when a repository needs to become a reliable scip-query workspace. A scip-query workspace is a source repository with a current SCIP index, runnable language indexers, installed agent skills, project guidance, and health evidence that agents can use before editing.
+
+## Rules
+
+1. Make local setup reliable before recommending cleanup.
+2. Do not run `scip-query setup-ci` in the default adoption path. CI is a separate explicit workflow.
+3. Treat missing capabilities as unavailable evidence, not as clean results.
+4. After setup, tell the user the health score and confirmed issue list before application-code cleanup begins.
+
+## Adoption Workflow
+
+### 1. Establish the project
+
+```bash
+pwd
+git rev-parse --show-toplevel
+scip-query --version
+```
+
+If `scip-query` is not available, install or link the package through the repo's package manager, then rerun the checks.
+
+### 2. Install skills and run setup
+
+```bash
+scip-query install-skills
+scip-query setup-hooks --json
+scip-query setup --json
+```
+
+Use `scip-query setup --git-hook --json` only when the user wants the local Git pre-commit diff-gate hook. Do not treat that hook as a replacement for final verification.
+Use `scip-query setup-hooks --json` when hook config needs to be repaired for the current repository without rerunning the full setup pass.
+
+### 3. Resolve blockers
+
+If setup reports `blocked` or `partial`, inspect dependencies and capabilities:
+
+```bash
+scip-query check-deps
+scip-query doctor
+scip-query capability-matrix --json
+scip-query status --capabilities
+```
+
+Fix missing indexers, toolchain dependencies, invalid config, or stale indexes. If a toolchain cannot be installed safely, record exact manual commands and keep the adoption state blocked.
+
+### 4. Initialize or validate config
+
+```bash
+scip-query init
+scip-query config-validate
+```
+
+Run `init` only when `.scipquery.json` is absent and the project needs config. Keep config minimal and evidence-backed. Use suppressions only for accepted findings with specific reasons:
+
+```bash
+scip-query suppress <id> --reason "<specific reason>"
+scip-query config-validate
+```
+
+### 5. Prove ongoing local usefulness
+
+```bash
+scip-query reindex
+scip-query stats
+scip-query files <known-source-term>
+scip-query outline <known-source-file>
+scip-query health --json --full
+scip-query diff-gate --json
+```
+
+Use `scip-query watch` only for an active local work session where automatic reindexing is useful. Do not leave it running as a hidden setup side effect.
+
+### 6. Hand off to health audit
+
+Invoke `scip-health-audit` after setup if the user wants cleanup or a perfect-code pass. The first user-facing message after the audit must include:
+
+- health score;
+- confirmed items that need attention;
+- unconfirmed signals;
+- unavailable or blocked checks;
+- recommended first cleanup batch.
+
+Then start cleanup only if the current request already asks for cleanup or the user approves the batch.
+
+## Adoption Report
+
+End with:
+
+```markdown
+Adoption: ready/partial/blocked
+
+Installed:
+- skills, hooks, indexers, config files, guidance files
+
+Capabilities:
+- available checks
+- unavailable checks and why
+
+Health:
+- score
+- dossier path
+- confirmed cleanup queue or audit handoff
+
+Verification:
+- `scip-query reindex`
+- `scip-query diff-gate --json`
+- targeted smoke commands
+
+Deferred:
+- CI setup, external toolchains, product decisions, or blocked checks
+```
+
+Do not claim adoption is ready until the index is current, core commands smoke-test, and `scip-query diff-gate --json` passes.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Adoption"
+  short_description: "Adopt scip-query in a repository"
+  default_prompt: "Set up scip-query in this repository, verify local capabilities, write the health dossier, and hand off confirmed cleanup work."

package/skills/scip-ai-cleanup/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: scip-ai-cleanup
 description: Clean up AI-generated code rot using scip-query's change-graph and verification tooling. Finds recent re-implementations of established code, drifting standards docs, speculative parameters, hidden coupling, and produces compiler-verified deletion plans. Sets up the CI ratchet so findings never regress.
-allowed-tools: [Bash, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
-keywords: [ai-slop, ai-generated, cleanup, duplicates, echo, doc-drift, standards, stale-docs, cleanup-plan, verify, co-change, ratchet, baseline, unused-params]
 ---
 
 # AI-Generated Code Cleanup with scip-query
@@ -92,7 +90,7 @@ or add a contract test that fails when one side changes without the other.
 ### Step 5: Compiler-verified deletion
 
 ```bash
-scip-query cleanup-plan --verify
+scip-query cleanup-plan --verify --json
 ```
 
 - Batches are ordered: batch 0 is graph-fact dead now; batch n is dead once
@@ -105,12 +103,22 @@ scip-query cleanup-plan --verify
 - The `blocked` list explains why candidates can't cascade (e.g. a spec file
   still references them).
 
+Apply only compiler-verified batches:
+
+```bash
+scip-query cleanup-apply --verified --batch 0
+```
+
+Use `--all` only after explicit human approval. Use `--force-dirty` only when
+you have inspected the touched files and know the existing edits are unrelated
+to the cleanup batch.
+
 ### Step 6: Ratchet it
 
 ```bash
 scip-query health --write-baseline   # commit .scipquery-baseline.json
 scip-query health --baseline         # exit 1 on any NEW finding — wire into CI
-scip-query diff-gate                 # per-diff gate: echoes, missing partners, uncited docs
+scip-query diff-gate --json          # per-diff gate: echoes, missing partners, uncited docs
 ```
 
 `diff-gate` is the leading indicator: run it on every agent commit / PR

package/skills/scip-ai-cleanup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP AI Cleanup"
+  short_description: "Clean up AI-generated code rot"
+  default_prompt: "Use $scip-ai-cleanup to find and fix AI-generated duplication, partial migrations, and stale cleanup fallout."

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

@@ -0,0 +1,147 @@
+---
+name: scip-api-impact
+description: Assess and plan public API, module boundary, schema, route, CLI, config, or exported-surface changes with scip-query evidence. Use when the user asks what will break, who consumes an API, how to migrate a boundary, whether a signature change is safe, or how to coordinate docs/tests/generated artifacts.
+---
+
+# SCIP API Impact
+
+Use this skill before changing a public surface. A public surface is a callable, export, route, schema, config field, CLI command, generated artifact, or documented behavior that other code or users can depend on. Its defining trait is that a local edit can require coordinated consumer, docs, test, or migration changes outside the implementation file.
+
+## Rules
+
+1. Identify the actual surface before planning the change.
+2. Use scip-query to find direct consumers, reverse dependencies, transitive blast radius, and historical co-change partners.
+3. Treat docs, generated files, tests, and config as part of the API when they describe or enforce the surface.
+4. Prefer backward-compatible migration plans when consumers are broad or external.
+5. Run `scip-verify` after implementation.
+
+## Workflow
+
+### 1. Identify the surface
+
+```bash
+scip-query status --capabilities
+scip-query reindex
+scip-query surface <module-or-package>
+scip-query outline <file>
+scip-query trace <symbol-or-command>
+scip-query code <symbol-or-command>
+```
+
+Use `scip-query hierarchy <symbol> --json` for class members or nested methods so you know whether the real surface is the member, class, module, or package.
+
+### 2. Find consumers and ownership
+
+```bash
+scip-query refs <symbol>
+scip-query fan-in <symbol>
+scip-query rdeps <file>
+scip-query affected <symbol> --json
+scip-query change-surface <file> --json --full
+```
+
+Record direct consumers separately from transitive consumers. Direct consumers must compile or adapt immediately; transitive consumers define blast radius and regression risk.
+
+### 3. Find hidden partners
+
+```bash
+scip-query co-change <file> --json --full
+scip-query doc-drift --json --full
+scip-query similar <symbol> --json --full
+scip-query similar-files <file> --json --full
+```
+
+Use co-change for schema/docs/generator/test partners that do not import each other. Use doc drift when docs mention the surface. Use similarity to find sibling APIs that should remain consistent.
+
+### 4. Choose the migration shape
+
+Pick one:
+
+- Compatible extension: add optional behavior without breaking existing callers.
+- Two-step migration: add the new surface, migrate callers, then remove the old surface.
+- Breaking change: update all consumers and docs in one coordinated change.
+- Adapter shim: keep a wrapper only when external consumers or compatibility windows require it.
+
+Reject speculative parameters or wrappers by running:
+
+```bash
+scip-query unused-params --json --full
+scip-query wrapper-candidates --json --full
+scip-query passthrough-candidates --json --full
+```
+
+### 5. Build the impact plan
+
+Before editing, write:
+
+```markdown
+Surface:
+- <symbol/file/command/schema>
+
+Consumers:
+- direct: <count and important files>
+- transitive: <count or affected clusters>
+
+Required co-changes:
+- code
+- tests
+- docs
+- generated files
+- config or schema partners
+
+Migration:
+- compatible extension / two-step / breaking / shim
+
+Verification:
+- targeted tests
+- `scip-query diff-impact --json`
+- `scip-query diff-gate --json`
+- `scip-query doc-drift --json --full` when docs changed
+- `scip-query config-validate` when config changed
+```
+
+### 6. Verify after editing
+
+```bash
+scip-query reindex
+scip-query diff-impact --json
+scip-query diff-gate --json
+```
+
+Then run routed checks:
+
+```bash
+scip-query unused-params --json --full
+scip-query incomplete-migration --json --full
+scip-query co-change <changed-file> --json --full
+scip-query doc-drift --json --full
+```
+
+Invoke `scip-verify` before declaring the API change ready.
+
+## Report Format
+
+```markdown
+API impact: low/medium/high
+
+Surface changed:
+- <surface>
+
+Consumers:
+- <direct consumers>
+- <transitive blast radius>
+
+Migration plan:
+- <chosen shape and why>
+
+Co-changes:
+- <docs/tests/generated/config partners>
+
+Verification:
+- <commands run and results>
+
+Remaining risk:
+- <external consumers, unavailable capabilities, or accepted compatibility shims>
+```
+
+Do not call a public-surface change safe until direct consumers, docs/config partners, and `scip-query diff-gate --json` have been checked.

package/skills/scip-api-impact/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP API Impact"
+  short_description: "Assess public API and boundary change impact"
+  default_prompt: "Assess the impact of this public API or module-boundary change with scip-query evidence and produce a migration-safe plan."

package/skills/scip-debloat/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: scip-debloat
-description: Comprehensive codebase de-bloating using scip-query. Finds dead code, duplication, unnecessary abstractions, consolidation opportunities, pattern drift, and structural bloat from every possible angle. Produces a prioritized action list.
-allowed-tools: [Bash, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
-keywords: [debloat, clean, cleanup, refactor, dead-code, duplication, dry, consolidate, simplify, reduce, bloat, unused, stale, drift, health]
+description: Comprehensive codebase de-bloating using scip-query. Use when the user asks to clean up a codebase, find dead code, delete bloat, remove duplication, consolidate variants, shrink a module, or audit structural waste. Finds dead code, duplication, unnecessary abstractions, pattern drift, and consolidation opportunities, then produces a prioritized action list. Use scip-health-improve instead when the user wants an autonomous health-score campaign.
 ---
 
 # Codebase De-Bloating with scip-query
@@ -13,16 +11,11 @@ This is not a score-maxing workflow. Health scores, finding counts, and LOC tota
 
 ---
 
-## When to Use This Skill
+## Scope Boundary
 
-- "Clean up this codebase"
-- "Find dead code"
-- "What can we delete?"
-- "Find duplication"
-- "Make this codebase smaller"
-- "Are there things we can consolidate?"
-- "Run a health check"
-- "De-bloat this module"
+Use `scip-debloat` for bloat-specific discovery and action planning. Use
+`scip-health-improve` when the user wants the agent to keep applying confirmed
+fixes until the health score is as high as reasonably possible.
 
 ---
 
@@ -49,7 +42,7 @@ This is not a score-maxing workflow. Health scores, finding counts, and LOC tota
 Before working the angles below one by one, run the high-leverage trio:
 
 ```bash
-scip-query cleanup-plan --verify     # cascade dead-code plan, COMPILER-VERIFIED per batch
+scip-query cleanup-plan --verify --json  # cascade dead-code plan, COMPILER-VERIFIED per batch
 scip-query recent-duplicates         # recent code that re-implements established code
 scip-query doc-drift                 # docs whose referenced code moved on without them
 ```
@@ -61,6 +54,15 @@ check) differentially. Only act on batches stamped COMPILER-VERIFIED; FAILED
 output names the references the static evidence missed. For AI-generated
 codebases specifically, prefer the dedicated scip-ai-cleanup skill.
 
+Apply one verified batch at a time:
+
+```bash
+scip-query cleanup-apply --verified --batch 0
+```
+
+Use `--all` only after explicit human approval. Use `--force-dirty` only after
+inspecting the touched files and confirming existing edits are unrelated.
+
 After cleanup, ratchet the result so it never regresses:
 
 ```bash

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Debloat"
+  short_description: "Find and remove structural bloat"
+  default_prompt: "Use $scip-debloat to find dead code, duplication, wrappers, stale abstractions, and other structural bloat."

package/skills/scip-debug/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: scip-debug
+description: Root-cause bugs and regressions with scip-query evidence. Use when the user reports a bug, failing behavior, regression, confusing runtime path, broken data flow, or asks to debug, diagnose, reproduce, trace, or explain why code behaves incorrectly before fixing it.
+---
+
+# SCIP Debug
+
+Use this skill to move from a reported failure to a minimal verified fix. A bug is a mismatch between expected behavior and observed behavior in a concrete execution path. A root cause is the earliest code fact in that path that explains the mismatch and makes the later symptoms possible.
+
+## Rules
+
+1. Reproduce or restate the failure before changing code.
+2. Use scip-query to identify entry points, call paths, data flow, and blast radius. Do not debug from filename guesses alone.
+3. Prefer one narrow fix over broad cleanup. If cleanup is also needed, record it after the bug fix unless it is required for correctness.
+4. Verify the fix with the repo's test or smoke command, then run `scip-verify`.
+
+## Workflow
+
+### 1. Pin the failure
+
+Record:
+
+- observed behavior;
+- expected behavior;
+- command, route, UI action, test, job, or file that exposes it;
+- error text or wrong output;
+- suspected time window if it is a regression.
+
+If the user provides no reproduction, make the smallest runnable reproduction you can from the repo's existing tests, scripts, CLI, or app entry points.
+
+### 2. Find the entry point
+
+```bash
+scip-query status --capabilities
+scip-query reindex
+scip-query files <feature-or-error-term>
+scip-query outline <candidate-file>
+scip-query trace <candidate-symbol>
+scip-query code <candidate-symbol>
+```
+
+Use `scip-query by-kind function --scope <scope>` or `scip-query kind-counts --scope <scope>` when the codebase is unfamiliar and you need an inventory before selecting an entry point.
+
+### 3. Follow execution
+
+```bash
+scip-query call-graph <entry-symbol>
+scip-query code <callee-symbol>
+scip-query refs <state-or-api-symbol>
+scip-query fan-in <suspect-symbol>
+scip-query fan-out <suspect-file>
+```
+
+Build the smallest path that explains the observed behavior. Stop expanding once the path reaches the first code fact that can cause the symptom.
+
+### 4. Follow data and state
+
+```bash
+scip-query dataflow <symbol-or-variable>
+scip-query slice <symbol-or-variable>
+scip-query slice <symbol-or-variable> --forward
+```
+
+Use dataflow when the bug looks like wrong state, wrong input normalization, missing validation, stale cache, dropped field, wrong async order, or an unexpected output value.
+
+### 5. Compare nearby implementations
+
+```bash
+scip-query similar <suspect-symbol> --json --full
+scip-query convergence <suspect-symbol> <similar-symbol>
+scip-query similar-files <suspect-file> --json --full
+```
+
+A similar implementation can reveal the missing branch, guard, conversion, lifecycle step, or error handling path. Preserve essential differences; do not copy behavior blindly.
+
+### 6. Bound the fix
+
+```bash
+scip-query change-surface <suspect-file> --json --full
+scip-query affected <suspect-symbol> --json
+scip-query diff-impact --json
+```
+
+Name the smallest symbol or file that should change. If the blast radius is larger than the bug's scope, explain why before editing.
+
+### 7. Fix and verify
+
+Apply the minimal code change, then run:
+
+```bash
+scip-query reindex
+scip-query diff-gate --json
+```
+
+Also run the narrowest repo test, app smoke test, or command that reproduces the failure. Invoke `scip-verify` before calling the bug fixed.
+
+## Report Format
+
+```markdown
+Bug: <observed mismatch>
+
+Entry point:
+- <file/symbol> from <command>
+
+Root cause:
+- <code fact> from <command>
+
+Fix:
+- <minimal change>
+
+Verification:
+- <repo test or smoke command>
+- `scip-query diff-gate --json`
+
+Remaining risk:
+- <blast radius, unavailable capability, or follow-up cleanup>
+```
+
+If no root cause is proven, say what evidence is missing and what command or reproduction would unblock it. Do not present a guess as a fix.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Debug"
+  short_description: "Root-cause bugs with scip-query evidence"
+  default_prompt: "Use scip-query to trace a bug from entry point to root cause, propose a minimal fix, and verify the blast radius."