scip-query 0.10.11 → 0.11.0

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

@@ -1,18 +1,48 @@
 ---
 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.
+description: Assess API impact with scip-query evidence. Use before changing public exports, module boundaries, schemas, routes, CLI commands, config fields, generated artifacts, signatures, docs-backed behavior, or consumer migrations.
+commands:
+  - template: "scip-query surface <module-or-package>"
+    when: "Identify the surface: what consumers actually use from the module."
+  - template: "scip-query refs <symbol>"
+    when: "Find consumers: every direct reference to the surface symbol."
+  - template: "scip-query affected <symbol> --json"
+    when: "Find consumers: transitive blast radius of the change."
+  - template: "scip-query co-change <file> --json --full"
+    when: "Find hidden partners: historically coupled files without a dependency edge."
+  - template: "scip-query doc-drift --json --full"
+    when: "Find hidden partners: docs that describe the surface and may need an update."
+  - template: "scip-query unused-params --json --full"
+    when: "Choose migration shape: reject speculative new parameters."
 ---
 
-# SCIP API Impact
+# 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.
+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, tests, or migration changes outside the implementation file.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query surface <module-or-package>` | What symbols consumers actually use from this module | Identify the surface: what consumers actually use from the module. |
+| `scip-query refs <symbol>` | Find all files referencing a symbol | Find consumers: every direct reference to the surface symbol. |
+| `scip-query affected <symbol> --json` | Transitive closure of symbols that could break if this symbol changes | Find consumers: transitive blast radius of the change. |
+| `scip-query co-change <file> --json --full` | Files that change together in git history without a dependency edge — hidden coupling candidates | Find hidden partners: historically coupled files without a dependency edge. |
+| `scip-query doc-drift --json --full` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | Find hidden partners: docs that describe the surface and may need an update. |
+| `scip-query unused-params --json --full` | Speculative-generality candidates: trailing parameters no body ever uses (TS/JS) | Choose migration shape: reject speculative new parameters. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
 
 ## 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.
+1. Identify the actual surface before planning.
+2. 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.
+4. Prefer backward-compatible migrations when consumers are broad or external.
 5. Run `scip-verify` after implementation.
 
 ## Workflow
@@ -20,19 +50,16 @@ Use this skill before changing a public surface. A public surface is a callable,
 ### 1. Identify the surface
 
 ```bash
-scip-query status --capabilities
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# 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>
+scip-query hierarchy <symbol> --json
 ```
 
-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.
+This step is complete only when the real surface is named: member, class, module, package, route, schema, command, or config field.
 
-### 2. Find consumers and ownership
+### 2. Find consumers
 
 ```bash
 scip-query refs <symbol>
@@ -42,7 +69,9 @@ 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.
+Record direct consumers separately from transitive consumers.
+
+This step is complete only when direct breakage and regression blast radius are known.
 
 ### 3. Find hidden partners
 
@@ -53,18 +82,18 @@ 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.
+This step is complete only when docs, generated files, fixtures, sibling APIs, and hand-synchronized partners are accounted for or ruled out.
 
-### 4. Choose the migration shape
+### 4. Choose 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.
+- Compatible extension.
+- Two-step migration.
+- Breaking coordinated change.
+- Adapter shim for external consumers or compatibility windows.
 
-Reject speculative parameters or wrappers by running:
+Reject speculative inputs and empty wrappers with:
 
 ```bash
 scip-query unused-params --json --full
@@ -72,80 +101,35 @@ scip-query wrapper-candidates --json --full
 scip-query passthrough-candidates --json --full
 ```
 
-### 5. Build the impact plan
+This step is complete only when the migration shape explains deploy order, rollback, and compatibility risk.
 
-Before editing, write:
+### 5. Build and verify the plan
 
 ```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`
+- invoke `scip-verify`
 - `scip-query doc-drift --json --full` when docs changed
 - `scip-query config-validate` when config changed
 ```
 
-### 6. Verify after editing
+After editing, run routed checks from the shared reference and invoke `scip-verify`.
 
-```bash
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
-scip-query diff-impact --json
-scip-query diff-gate --json
-```
+The work is complete only when direct consumers, docs/config partners, and `scip-verify` have been checked.
 
-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
+## Report
 
 ```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-claim-audit/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: scip-claim-audit
+description: Audit output-facing status claims for evidence with scip-query. Use to 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.
+commands:
+  - template: "scip-query files <pattern>"
+    when: "Inventory: locate the renderer or status-producing module for a claim."
+  - template: "scip-query refs <symbol>"
+    when: "Classify: find every producer and consumer of a status-bearing function."
+  - template: "scip-query code <symbol>"
+    when: "Classify: read the producing function to see whether it computes or asserts."
+  - template: "scip-query trace <symbol>"
+    when: "Classify: definition plus every reference for a status field or constant."
+  - template: "scip-query capabilities --matrix --json"
+    when: "Spot-check: an already-known example of a fixed derived-status surface."
+---
+
+# scip-claim-audit
+
+Use this skill to find agent-facing claims that sound verified but are not. A status word is **derived** when its producer computes it from a real probe, scan, or computation (a compiler run, a runtime capability probe, a graph traversal). It is **hedged** when the code or its label already says it is a candidate, heuristic, or unverified. It is **asserted** when 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 skill exists to find.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query files <pattern>` | Find files matching a pattern | Inventory: locate the renderer or status-producing module for a claim. |
+| `scip-query refs <symbol>` | Find all files referencing a symbol | Classify: find every producer and consumer of a status-bearing function. |
+| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Classify: read the producing function to see whether it computes or asserts. |
+| `scip-query trace <symbol>` | Trace a symbol: definition + all references | Classify: definition plus every reference for a status field or constant. |
+| `scip-query capabilities --matrix --json` | Report which evidence and verification capabilities are available in this project | Spot-check: an already-known example of a fixed derived-status surface. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Rules
+
+1. 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.
+2. Classify status, don't just list it: every status word in scope gets exactly one of derived / hedged / asserted.
+3. Severity follows the rubric: asserted + agent-facing + trust-bearing = high; asserted + internal-only or low-consequence = low; hedged is not a finding (the label already discloses uncertainty).
+4. 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.
+5. File findings as a table, not prose; a claim → producer → classification → fix format is the deliverable.
+
+## Workflow
+
+### 1. Inventory the status vocabulary
+
+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`. For each hit, note the file:line and the renderer or JSON field that surfaces it to an agent or user.
+
+```bash
+scip-query files <target-file-or-pattern>
+```
+
+This step is complete only when every status-bearing string or field in scope is listed with its surface (human output, `--json` field, or both).
+
+### 2. Classify each producer
+
+For each status word's producing function:
+
+```bash
+scip-query refs <producing-function>
+scip-query code <producing-function>
+scip-query trace <status-field-or-constant>
+```
+
+Read the function body. Classify:
+
+- **Derived**: the status is computed from a probe, scan, spawn result, file check, or graph query performed at or near that call site.
+- **Hedged**: the label, descriptor evidence tier, or surrounding text already marks the value as heuristic, candidate, or unverified.
+- **Asserted**: the value is a literal, a static table lookup, or a branch that returns a fixed status without invoking any check for that specific branch.
+
+This step is complete only when every producer has one of these three labels with the one line of source evidence that justifies it.
+
+### 3. File findings for every asserted status
+
+For each **asserted** status, apply the severity rubric (rule 3) and write:
+
+```markdown
+Claim: <status word and where it appears>
+Producer: <file:line function name>
+Classification: asserted
+Severity: high/low
+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)
+```
+
+This step is complete only 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).
+
+### 4. Report
+
+Write the report under `docs/scip-query/` unless the user asked only for a conversational answer.
+
+```markdown
+Scope:
+Status words inventoried: N
+
+Claim table:
+| Claim | Producer | Classification | Fix |
+| --- | --- | --- | --- |
+
+Fixed since last audit:
+- <claim> — now derived via <probe>, no longer a finding.
+```
+
+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-claim-audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Claim Audit"
+  short_description: "Classify output-facing status claims as derived, hedged, or asserted"
+  default_prompt: "Use scip-query to inventory output-facing status words in the target scope, classify each producer as derived, hedged, or asserted, and file findings for asserted trust-bearing claims."

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

@@ -0,0 +1,122 @@
+---
+name: scip-cleanup-audit
+description: Audit and rank scip-query cleanup signals without editing code. Use for health reports, de-bloat reports, recent AI residue audits, score-framed cleanup queues, confirming raw findings, or preparing a cleanup plan.
+commands:
+  - template: "scip-query health --json"
+    when: "Establish evidence: composite score and prioritized action list."
+  - template: "scip-query cleanup-plan --verify --json"
+    when: "Sweep signals: compiler-verified deletion plan, batched."
+  - template: "scip-query duplicate-bodies --json --full"
+    when: "Sweep signals: exact duplicate small-body candidates."
+  - template: "scip-query recent-duplicates --json --full"
+    when: "Sweep signals: recent code that re-implements established code."
+  - template: "scip-query incomplete-migration --json --full"
+    when: "Sweep signals: partially-completed extractions."
+  - template: "scip-query doc-drift --json --full"
+    when: "Sweep signals: stale docs referencing changed code."
+---
+
+# scip-cleanup-audit
+
+Use this skill to turn raw scip-query signals into a confirmed cleanup queue. Do not edit application code in this skill.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query health --json` | Composite codebase health report with prioritized action list | Establish evidence: composite score and prioritized action list. |
+| `scip-query cleanup-plan --verify --json` | Ordered, batched deletion plan: graph-fact dead code plus the cascade candidates it unlocks | Sweep signals: compiler-verified deletion plan, batched. |
+| `scip-query duplicate-bodies --json --full` | Find exact duplicate small-body candidates across files | Sweep signals: exact duplicate small-body candidates. |
+| `scip-query recent-duplicates --json --full` | Directional duplicate candidates: recent code that re-implements established callable, React, or Vue code | Sweep signals: recent code that re-implements established code. |
+| `scip-query incomplete-migration --json --full` | Partially-completed extraction candidates: new helpers in the diff wired into some sites while similar un-migrated sites remain | Sweep signals: partially-completed extractions. |
+| `scip-query doc-drift --json --full` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | Sweep signals: stale docs referencing changed code. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Modes
+
+- Whole-repo audit: rank all cleanup signals.
+- Recent AI residue: focus on echoes, twins, incomplete migrations, speculative params, stale agent-facing docs, and hidden couplings.
+- Score-framed audit: explain health score deductions and the safest first batch.
+
+## Workflow
+
+### 1. Establish evidence
+
+```bash
+scip-query doctor
+scip-query status --capabilities
+scip-query health --json
+scip-query capabilities --json
+scip-query config-validate --json
+```
+
+This step is complete only when unavailable capabilities are recorded as unavailable.
+
+### 2. Sweep signals
+
+Run every relevant class, or record why it is unavailable:
+
+```bash
+scip-query cleanup-plan --verify --json
+scip-query duplicate-bodies --json --full
+scip-query recent-duplicates --json --full
+scip-query incomplete-migration --json --full
+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
+scip-query doc-drift --json --full
+```
+
+For frontend repos, add the React or Vue duplicate, hook/composable, and large-component/view commands.
+
+Optional deep-dive (near-zero precision on codebases with intentional layering/ambient types — run only when the sweep above is exhausted, and treat every hit as a lead to confirm, not a finding):
+
+```bash
+scip-query stale-abstractions --json --full
+scip-query wrapper-candidates --json --full
+```
+
+### 3. Confirm candidates
+
+For each high-priority candidate, inspect source and graph evidence:
+
+```bash
+scip-query code <symbol-or-file>
+scip-query refs <symbol>
+scip-query fan-in <symbol>
+scip-query fan-out <symbol-or-file>
+scip-query affected <symbol> --json
+scip-query change-surface <file> --json --full
+scip-query similar <symbolA> <symbolB> --plan
+scip-query co-change <file> --json --full
+```
+
+Classify every candidate as `confirmed fix target`, `intentional design`, `false positive`, or `blocked`.
+
+### 4. Report
+
+```markdown
+Health score: N/100
+
+Confirmed items:
+- [priority] finding - evidence - first safe action
+
+Unconfirmed signals:
+- signal - evidence still needed
+
+Unavailable or blocked checks:
+- check - reason
+
+Recommended first cleanup batch:
+- batch - why safe now
+```
+
+The audit is complete only when each collected signal is classified and the next action is visible.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Cleanup Audit"
+  short_description: "Confirm and rank cleanup, de-bloat, and recent AI residue signals without editing"
+  default_prompt: "Audit scip-query cleanup signals, classify findings with evidence, and report the safest next cleanup batch."

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

@@ -0,0 +1,84 @@
+---
+name: scip-cleanup-improve
+description: Improve scip-query health autonomously with verified cleanup. Use when the user asks to fix cleanup findings, raise health, keep cleaning, continue after setup, or work until no safe confirmed cleanup remains.
+commands:
+  - template: "scip-query health --json"
+    when: "Before editing: report current score and remaining signals."
+  - template: "scip-query cleanup-plan --verify --json"
+    when: "Loop: confirm the next compiler-verified deletion batch."
+  - template: "scip-query cleanup-apply --verified --batch <n>"
+    when: "Loop: apply one verified deletion batch."
+  - template: "scip-query duplicate-bodies --json --full"
+    when: "Priority: exact duplicate small-body echoes to consolidate."
+  - template: "scip-query incomplete-migration --json --full"
+    when: "Priority: un-migrated call sites left behind by a new helper."
+---
+
+# scip-cleanup-improve
+
+Use this skill for bounded autonomous cleanup. The target is not score chasing; the target is fixing confirmed issues that make the codebase harder to understand, verify, or change.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query health --json` | Composite codebase health report with prioritized action list | Before editing: report current score and remaining signals. |
+| `scip-query cleanup-plan --verify --json` | Ordered, batched deletion plan: graph-fact dead code plus the cascade candidates it unlocks | Loop: confirm the next compiler-verified deletion batch. |
+| `scip-query cleanup-apply --verified --batch <n>` | Apply a compiler-verified cleanup-plan batch to the working tree | Loop: apply one verified deletion batch. |
+| `scip-query duplicate-bodies --json --full` | Find exact duplicate small-body candidates across files | Priority: exact duplicate small-body echoes to consolidate. |
+| `scip-query incomplete-migration --json --full` | Partially-completed extraction candidates: new helpers in the diff wired into some sites while similar un-migrated sites remain | Priority: un-migrated call sites left behind by a new helper. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Rules
+
+1. Start with `scip-cleanup-audit` evidence or run the audit sweep yourself.
+2. Report current health and the first confirmed batch before editing.
+3. Prioritize high-confidence, low-blast-radius, clearly verifiable fixes.
+4. Apply one small batch at a time.
+5. After a cleanup pass, run `scip-query health --write-baseline` to snapshot finding identities, then compare with `scip-query health --baseline` at the start of the next pass.
+
+## Priority
+
+1. Compiler-verified deletion batches.
+2. Incomplete migrations and recent duplicate echoes.
+3. Unused params, unused imports, dead symbols, and isolated symbols.
+4. Broken or stale docs, config validation issues, and missing co-change partners.
+5. Thin wrappers, passthroughs, stale abstractions, and speculative generality.
+6. Frontend component/hook/composable duplication and large-view pressure.
+7. Directory architecture and maintainability repairs only when evidence is strong and the blast radius is bounded.
+
+## Loop
+
+Before editing:
+
+```markdown
+Health score: N/100
+First confirmed batch:
+- finding - evidence - planned fix - verification
+Remaining signals:
+- signal - status
+```
+
+Then repeat:
+
+1. Apply one verified deletion batch or one small targeted refactor.
+2. Run the narrow project check for touched behavior.
+3. Run `scip-query health --json`.
+4. Invoke `scip-verify`.
+5. If `docs/scip-query/health-dossier.md` exists (or a custom `--dossier-dir` was used), refresh it by rerunning `scip-query setup --json` (add the same `--dossier-dir` if one was used).
+6. Pick the next highest-priority confirmed item.
+
+Use `scip-query cleanup-apply --verified --batch <n>` for verified deletion batches. Use `--all` only with explicit user approval.
+
+## Stop
+
+Stop when only intentional, false-positive, blocked, or unconfirmed items remain; when the next improvement needs a product/API/ownership decision; when a missing toolchain prevents trustworthy verification; or when further work would be broad redesign rather than bounded cleanup.
+
+## Closeout
+
+Report starting and final health scores, batches applied, important files changed, verification commands, remaining accepted or blocked items, and highest-value follow-up.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Cleanup Improve"
+  short_description: "Fix confirmed cleanup findings batch by batch with verification"
+  default_prompt: "Improve scip-query health by fixing confirmed cleanup findings one verified batch at a time."