scip-query 0.20.0 → 0.21.0

package/skills/scip-diagnose/references/root-cause.md

@@ -1,145 +0,0 @@
-# Root cause: recurring bug family → design flaw → least invasive remedy
-
-Use this mode to move from a family of related bugs to the design flaw that
-produces them, and to the least invasive remedy that eliminates the class.
-Debug mode takes one failure to one minimal fix; the maintainability scenario
-in `scip-audit` finds structural smells without bug evidence; this mode starts
-from evidence that patching has not worked — the same kind of bug keeps
-recurring — and asks what the system's design gets wrong.
-
-Load shared mechanics from [`../../_shared/SKILL.md`](../../_shared/SKILL.md) only when this shortlist is insufficient.
-
-## Commands used in this mode
-
-| Command | When |
-| --- | --- |
-| `scip-query trace <mechanism-symbol>` | Assemble the family: mechanism and violated invariant for each bug (bounded coverage: definition sites with source/signature, referencing files with line numbers). |
-| `scip-query code <mechanism-symbol>` / `scip-query dataflow <mechanism-symbol>` | Assemble the family: trace each bug's mechanism to source rather than a symptom description. |
-| `scip-query co-change <fix-site-file>` | Assemble the family: files that historically changed together with each fix site without a dependency edge — hidden coupling candidates, and a way to find family members the user forgot (bounded coverage: file pairs, co-change counts, confidence, history context). |
-| `scip-query system <system-scope>` | Define the system's real responsibilities, files, and dependencies in and out (complete coverage: module file paths, exported symbols with line ranges, internal and reverse dependencies). |
-| `scip-query surface <system-scope>` | Define the system: referents for its public surface alongside `system`. |
-| `scip-query similar <fixed-symbol> --full` | Predict: hunt latent instances among sibling implementations of the fixed code (bounded coverage). |
-| `scip-query refs <invariant-carrier>` | Predict: every site that touches the violated invariant's state (bounded coverage: referencing file paths, reference line numbers grouped by file). |
-| `scip-query affected <remedy-symbol>` | Choose the remedy rung: blast radius of the candidate remedy (bounded coverage: transitive closure of symbols that could break). |
-
-## Terms
-
-A **bug family** is a set of failures whose mechanisms violate the same invariant; what makes it a family rather than a coincidence is that one stated flaw derives every member, so fixing members one at a time treats symptoms of a shared cause.
-
-A **design flaw** is a mismatch between what a system's design assumes and what its real responsibilities require; what makes it the root cause is that it is the earliest fact from which every family member's mechanism follows, so removing it removes the class.
-
-**Retrodiction** is deriving each already-known bug from the hypothesized flaw; what makes it a test is that a family member the flaw cannot derive either shrinks the family or kills the hypothesis.
-
-A **latent instance** is a not-yet-reported bug the flaw predicts must exist in unfixed code; what makes it decisive is that it is checkable now — finding one confirms the diagnosis and becomes a fix target, while an honest hunt that finds none weakens the diagnosis and must be reported as weakening it.
-
-The **remedy ladder** is the ordered set of interventions from least to most invasive; what makes the order binding is that each rung is only justified when a constructed family member survives the rung below it.
-
-## Rules
-
-1. Every bug in the family gets a mechanism traced to source, not a symptom description: which invariant broke, where, and what the fix did. Sources: fix commits (`git log --follow`, `git show`) plus `trace`/`code`/`dataflow`.
-2. The flaw hypothesis must be falsifiable and stated as a design claim — "the design assumes X, but the system's responsibilities include Y" — never as a narrative about unlucky bugs.
-3. State at least two rivals and kill them with evidence: unrelated coincidences, caller misuse rather than design, one missed edge case rather than a structural flaw.
-4. The hypothesis must retrodict every family member and predict at least one latent instance, and the latent-instance hunt must be executed (`similar`, `refs` over the invariant's carriers, or a constructed probe), not merely argued.
-5. Choose the lowest remedy rung that kills the whole class — retrodicted and latent members both. Climb a rung only when a constructed family member survives the rung below, and keep that counterexample in the record.
-6. Root-cause stories are the most rationalization-prone artifact in software: prefer delegating the attack on the diagnosis and the remedy to a fresh subagent given only the family table, system definition, and hypothesis — briefed to win by refuting it. Solo fallback: write the rival hypotheses and the latent-instance predictions before reading any more code.
-7. The verdict is derived with counts, and the diagnosis hands off to
-   `scip-plan` for implementation — this mode does not edit application code
-   itself.
-
-## Workflow
-
-### 1. Assemble the bug family
-
-For each reported or fixed bug, fill one row:
-
-```markdown
-| Bug | Symptom | Mechanism (file:symbol) | Invariant violated | Fix applied | Source |
-| --- | ------- | ----------------------- | ------------------ | ----------- | ------ |
-```
-
-Evidence: the user's description, fix commits (`git log --follow`, `git show`), `scip-query trace`/`code` on the mechanism symbols, `scip-query co-change` on fix sites to find members the user forgot.
-
-This step is complete only when every row has a source-traced mechanism and a named invariant — a bug whose mechanism cannot be traced is listed as `unconfirmed member`, not silently included.
-
-### 2. Define the system
-
-Define the system that owns the family, contextually: its wider class, then the essential responsibility that explains its other traits in this codebase — with referents from `scip-query system <scope>` and `surface <scope>`. Then list the design's load-bearing assumptions as the code actually embodies them (not as the README states them), each with a `Source:` citation.
-
-This step is complete only when the system's real responsibilities and embodied assumptions are stated with citations.
-
-### 3. Hypothesize the flaw — and its rivals
-
-State the flaw as a falsifiable design claim:
-
-```markdown
-Flaw hypothesis: the design assumes <X> (Source: <citation>), but the system's
-responsibilities include <Y> (Source: <citation>); every family member is an
-instance of the X∧Y collision.
-
-Rivals:
-
-- R1. Coincidence — the members have unrelated causes. Killed by: <evidence> | ALIVE
-- R2. Misuse — callers hold the bug, the design is sound. Killed by: <evidence> | ALIVE
-- R3. <next-most-plausible> — Killed by: <evidence> | ALIVE
-```
-
-A rival still marked `ALIVE` at the end of the workflow caps the diagnosis at `CANDIDATE`, not `CONFIRMED`.
-
-### 4. Retrodict and predict
-
-Retrodiction: derive each family-table row from the flaw in one sentence each. A member that cannot be derived is removed from the family (say so) or refutes the hypothesis (start over).
-
-Prediction: the flaw implies unfixed instances exist. Name where they must be, then hunt:
-
-```bash
-scip-query similar <fixed-symbol> --full
-scip-query refs <invariant-carrier>
-```
-
-plus a constructed probe when the claim is cheaply executable. Record each prediction with an executed result:
-
-```markdown
-- L1. <predicted latent instance> → FOUND at <file:line> (new fix target) | NOT FOUND after <hunt executed>
-```
-
-This step is complete only when every family member is retrodicted and every prediction has an executed hunt result. Zero latent instances found is a reportable weakness of the diagnosis, not a detail to omit.
-
-### 5. Choose the lowest rung
-
-The remedy ladder, in order:
-
-1. **Enforce the invariant at a boundary** — type, guard, constraint, lint, trigger — without moving code.
-2. **Consolidate the responsibility into one owner** — the scattered decision gets one named mechanism.
-3. **Redesign the core behind its existing interface** — consumers untouched.
-4. **Redesign the interfaces** — last resort; consumers migrate.
-
-For the chosen rung, run the attack: construct a family member — retrodicted
-or latent — that survives the rung. If one survives, keep the counterexample
-in the record and climb one rung. Check blast radius with
-`scip-query affected` before proposing any rung above 1. For protocol- or
-lifecycle-shaped flaws whose remedy must hold across interleavings, note the
-escalation path to the TLA+ mode in `scip-plan`.
-
-This step is complete only when the chosen rung has an attack record showing no family member survives it, and every rejected lower rung keeps its surviving counterexample.
-
-### 6. Report and hand off
-
-```markdown
-## Root-cause diagnosis
-
-System: <definition with referents>
-Bug family: <n> members traced, <u> unconfirmed
-Flaw: <the design claim> — CONFIRMED | CANDIDATE (rival <id> alive)
-Rivals: <r> stated, <k> killed with evidence
-Retrodiction: <n>/<n> members derived
-Latent instances: <p> predicted, <f> found (each a fix target), hunts executed
-Remedy: rung <1-4> — <the intervention>; lower rungs rejected by <counterexamples>
-Blast radius: <affected summary>
-Escalation: <none | scip-plan TLA+ mode for <property>>
-```
-
-Hand the diagnosis to `scip-plan`: the flaw and invariants constrain current
-flow and risks, the family table and hunt results constrain the slices, and
-the surviving-counterexample record seeds the verification attacks.
-
-The diagnosis is complete only when the verdict line carries the counts and every count is backed by an entry in the record above it.

package/skills/scip-diagnose/references/triage.md

@@ -1,119 +0,0 @@
-# Triage: raw report → grounded fix packet
-
-Use this mode to turn a report into a grounded fix packet. Triage is the evidence pass that determines whether the issue is reproducible, where it enters the codebase, what root cause is likely, and what test should fail before the fix.
-
-Load shared mechanics from [`../../_shared/SKILL.md`](../../_shared/SKILL.md) only when this shortlist is insufficient.
-
-## Commands used in this mode
-
-| Command | When |
-| --- | --- |
-| `scip-query files <issue-term>` | Map ownership: locate files for the reported term (complete coverage: matching file paths). |
-| `scip-query outline <candidate-file>` | Map ownership: enumerate symbols in a candidate owner file. |
-| `scip-query system <module-or-scope>` / `scip-query surface <module-or-scope>` | Map ownership: the module's real shape and public surface for broad subsystems. |
-| `scip-query kind-counts` / `scip-query by-kind` | Map ownership: orient in broad or unfamiliar subsystems. |
-| `scip-query trace <entry-or-error-symbol>` | Trace the failing path: definition plus every reference (bounded coverage: definition sites with source/signature, referencing files with line numbers). |
-| `scip-query code <entry-or-error-symbol>` | Trace the failing path: read the exact source (complete coverage: definition identity, source, line range). For stack traces, read the exact range with `scip-query code 'file:start-end'`. |
-| `scip-query call-graph <entry-symbol>` | Trace the failing path: callers and callees (bounded coverage). |
-| `scip-query dataflow <state-or-input-symbol>` / `scip-query slice <state-or-input-symbol>` | Trace the failing path: data flow and slices from the suspect input or state. |
-| `scip-query similar <suspect-symbol> --full` | Compare and bound: nearby implementations for missing handling (bounded coverage: symbol pairs, similarity scores, shared evidence). |
-| `scip-query similar <suspect-symbol> <comparison-symbol> --plan` | Compare and bound: two specific implementations directly. |
-| `scip-query similar-files <suspect-file> --full` | Compare and bound: nearby files for missing handling. |
-| `scip-query co-change <suspect-file> --full` | Compare and bound: files that historically changed with the suspect file. |
-| `scip-query change-surface <suspect-file> --full` | Compare and bound: exports, consumers, and blast-radius risk. |
-| `scip-query affected <suspect-symbol>` | Compare and bound: transitive impact bound for the fix plan (bounded coverage). |
-
-## Rules
-
-1. Do not file or implement a fix from the issue title alone.
-2. Use scip-query for code evidence: entry points, references, call flow, data flow, blast radius, and similar implementations.
-3. Prefer a failing test plan before a code plan.
-4. If the user asks only for triage, stop at the packet. If they also asked to fix it, implement only after the packet is clear.
-
-## Workflow
-
-### 1. Normalize the report
-
-Record summary, observed behavior, expected behavior, reproduction, affected surface, severity, user impact, and logs/screenshots/tests/links.
-
-Ask the user only for product intent, credentials, private data, or external system state that the repo cannot answer.
-
-This step is complete only when missing facts are either recovered or named.
-
-### 2. Map ownership
-
-```bash
-scip-query files <issue-term>
-scip-query outline <candidate-file>
-scip-query system <module-or-scope>
-scip-query surface <module-or-scope>
-```
-
-Use `kind-counts` and `by-kind` for broad subsystems.
-
-This step is complete only when likely owner files and surfaces are named.
-
-### 3. Trace the failing path
-
-```bash
-scip-query trace <entry-or-error-symbol>
-scip-query code <entry-or-error-symbol>
-scip-query call-graph <entry-symbol>
-scip-query dataflow <state-or-input-symbol>
-scip-query slice <state-or-input-symbol>
-```
-
-For stack traces, read the exact range with `scip-query code 'file:start-end'`.
-
-This step is complete only when a suspected root cause is tied to source evidence or labeled unproven.
-
-### 4. Compare and bound
-
-```bash
-scip-query similar <suspect-symbol> --full
-scip-query similar <suspect-symbol> <comparison-symbol> --plan
-scip-query similar-files <suspect-file> --full
-scip-query co-change <suspect-file> --full
-scip-query change-surface <suspect-file> --full
-scip-query affected <suspect-symbol>
-```
-
-This step is complete only when the packet has a narrow test shape and an impact bound.
-
-## Packet
-
-```markdown
-## Issue
-
-<one-sentence mismatch>
-
-## Reproduction
-
-<steps, command, failing test, or missing data>
-
-## Evidence
-
-- <scip-query command>: <fact>
-
-## Suspected Root Cause
-
-<earliest code fact that explains the symptom>
-
-## Impact
-
-- users/surfaces affected
-- blast radius
-
-## Fix Plan
-
-1. Add or update failing test/smoke check.
-2. Make the smallest code change.
-3. Run targeted test.
-4. Invoke `scip-verify`.
-
-## Open Questions
-
-- <product intent or external state only>
-```
-
-If no root cause is proven, label the issue `needs reproduction` or `needs product decision` rather than asserting one.

package/skills/scip-explore/references/diagrams.md

@@ -1,40 +0,0 @@
-# Diagrams
-
-Use this for code flow diagrams, architecture diagrams, data-flow maps, dependency maps, blast-radius visuals, module maps, or any HTML artifact that explains a system — built from `scip-query` evidence. A code diagram is an HTML artifact that turns source units, calls, dependencies, data flow, or blast radius into a visual map. Every node and edge must trace to `scip-query` evidence — gather it before drawing.
-
-## Workflow
-
-**1. Pick the diagram type.** Map the user's intent to a diagram type:
-
-| Intent | Diagram type |
-|---|---|
-| Feature flow | Call flow |
-| Value origin or mutation | Data flow |
-| Who depends on this | Blast radius |
-| Module architecture | Dependency map |
-| Why this is hard to change | Change surface / bottleneck map |
-| Classes or ownership | Hierarchy and surface map |
-
-Done when: the diagram's node and edge types are chosen.
-
-**2. Collect evidence.** Use only the commands the chosen diagram type needs, from:
-
-- `system <module>` — module map (file paths, exported symbols with line ranges, internal/reverse deps) for a dependency or architecture diagram.
-- `trace <symbol>` — definition sites plus all references, for a call-flow diagram.
-- `call-graph <symbol>` — incoming callers and outgoing callees, for a call-flow diagram.
-- `dataflow <symbol>` — definition sites, usage sites, producer symbols, consumer symbols, for a data-flow diagram.
-- `affected <symbol> --json` — transitive closure of symbols that could break if this symbol changes, for blast-radius nodes and edges.
-- `change-surface <file> --json --full` — exports, external consumer counts, and risk levels, for a change-surface map.
-- Also available as needed: `surface`, `outline`, `code`, `slice`, `slice --forward`, `deps`, `rdeps`, `hierarchy --json`, `fan-out --json`.
-
-Done when: every planned node and edge has a source command behind it.
-
-**3. Build the artifact.** Write it to `docs/scip-query/diagrams/YYYY-MM-DD-<scope>.html`. It must include: title, scope, summary, the visual diagram, a legend, an evidence table (which command produced which nodes/edges — command provenance lives inside the artifact, not just in your chat reply), omitted/collapsed nodes, and unavailable capabilities. Use inline CSS and semantic HTML or inline SVG: stable dimensions, wrapping labels, accessible colors, and distinct edge styles for calls, data, dependencies, and risk. Scope large graphs into clusters instead of rendering a hairball.
-
-Done when: the HTML contains both the visual diagram and the provenance/evidence table.
-
-**4. Verify.** Open the diagram file locally, or use a browser/screenshot tool when available. Confirm: the diagram is nonblank, labels don't overlap badly, and major nodes/edges trace to evidence. If the diagram is part of a docs/code change, invoke `scip-verify`.
-
-End the deliverable with the file path and a statement of what the diagram proves.
-
-Load shared mechanics from `../_shared/SKILL.md` — use this skill's own command shortlist first and open `_shared` only when it's insufficient.

package/skills/scip-explore/references/language-playbook.md

@@ -1,49 +0,0 @@
-# Language playbook
-
-Choose the shortest command path from "what is this system doing?" to a verified, language-specific answer. Start with the active language's row before reaching for broader or noisier commands. Pair relationship commands (`call-graph`, `imports`, `imported-by`, `refs`) with `code` to confirm behavior claims — don't stop at the relationship alone. For de-bloat work, cross-check multiple detector families rather than trusting one. When a command is weaker for a given language, use that language's fallback note instead of forcing it.
-
-## Universal first pass (any language)
-
-Run in order: `stats` (repo-wide size/shape, complete) → `kind-counts` → `files <feature-or-module-name>` (locate the files, complete) → `outline <file>` (symbol tree with line ranges, complete) → `by-kind function --scope <feature-or-module-name>` → `trace <symbol>` (definition + every reference, bounded) → `hierarchy <symbol>` → `code <symbol>` (confirm behavior with source, complete).
-
-## Per-language shortlists
-
-Each row gives the commands to reach for first, a de-bloat set for cleanup passes, and a fallback note for where that language's evidence is weaker or stronger than usual.
-
-**TypeScript** — first: `system`, `surface`, `call-graph`, `dataflow`, `change-surface`. De-bloat: `health`, `dead`, `similar`, `similar --plan`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `unused-imports`, `redundant-reexports`. Fallback: strongest verified surface of any language here; Vue script blocks use this same command path.
-
-**Python** — first: `outline`, `kind-counts --scope`, `system`, `imports`, `imported-by`, `call-graph`. De-bloat: `dead`, `unused-imports`, `drift`, `similar-signatures`, `complexity`, `complexity-hotspots`. Fallback: prefer source-backed fallbacks when call/kind metadata is sparse.
-
-**Java** — first: `system`, `surface`, `call-graph`, `deps`, `rdeps`, `slice`. De-bloat: `health`, `dead`, `similar-files`, `similar-chains`, `wrapper-candidates`, `stale-abstractions`, `extract-candidates`. Fallback: use module/package surfaces to avoid class-only tunnel vision.
-
-**Scala** — first: `surface`, `trace`, `call-graph`, `imports`, `imported-by`. De-bloat: `dead`, `similar-files`, `similar-chains`, `extract-candidates`, `stale-abstractions`, `unused-imports`. Fallback: confirm behavior with `code`.
-
-**Kotlin** — first: `surface`, `trace`, `call-graph`, `imports`, `imported-by`. De-bloat: `dead`, `similar-files`, `similar-chains`, `extract-candidates`, `stale-abstractions`, `unused-imports`. Fallback: confirm behavior with `code`.
-
-**Rust** — first: `trace`, `call-graph`, `refs`, `methods`, `surface`. De-bloat: `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-signatures`, `redundant-reexports`. Fallback: `methods` and `surface` are usually high signal here.
-
-**Go** — first: `surface`, `trace`, `call-graph`, `refs`, `fan-in`. De-bloat: `dead`, `wrapper-candidates`, `passthrough-candidates`, `similar-files`, `similar-signatures`, `complexity`. Fallback: use package-level surfaces and confirm exported APIs before cleanup.
-
-**C++** — first: `trace`, `refs`, `methods`, `surface`, `code`. De-bloat: `dead`, `wrapper-candidates`, `similar-files`, `similar-chains`, `extract-candidates`, `unused-imports`. Fallback: try `call-graph` after trace/refs/code.
-
-**C** — first: `trace`, `call-graph`, `refs`, `outline`, `fan-out`. De-bloat: `dead`, `wrapper-candidates`, `similar-files`, `similar-chains`, `extract-candidates`, `unused-imports`. Fallback: skip class/member commands — they don't apply.
-
-**Ruby** — first: `trace`, `call-graph`, `refs`, `imports`, `imported-by`. De-bloat: `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-files`, `similar-signatures`. Fallback: confirm dynamic-looking paths with source.
-
-**C#** — first: `surface`, `call-graph`, `trace`, `methods`, `refs`. De-bloat: `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-files`, `extract-candidates`. Fallback: use surfaces and methods together.
-
-**Visual Basic** — first: `surface`, `call-graph`, `trace`, `methods`, `refs`. De-bloat: `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-files`, `extract-candidates`. Fallback: use surfaces and methods together.
-
-**Dart** — first: `surface`, `call-graph`, `trace`, `imports`, `imported-by`. De-bloat: `dead`, `wrapper-candidates`, `stale-abstractions`, `similar-files`, `similar-signatures`, `redundant-reexports`. Fallback: confirm exported API shape with `surface`.
-
-**PHP** — first: `trace`, `refs`, `methods`, `surface`, `code`. De-bloat: `dead`, `wrapper-candidates`, `stale-abstractions`, `similar-files`, `similar-signatures`, `extract-candidates`. Fallback: try `call-graph` after trace/refs/code.
-
-**Clojure / ClojureScript** — first: `files`, `outline`, `trace`, `refs`, `call-graph`. De-bloat: `dead`, `similar-files`, `similar-signatures`, `complexity`, `complexity-hotspots`. Constraint: SCIP indexing comes from scip-clojure — there is no TypeScript-style semantic provider available for it, so don't expect the same depth of type-aware results.
-
-## Minimal workflows
-
-**Understand a feature:** `files <feature>` → `outline <file>` → `kind-counts --scope <feature>` → `fan-out <file>` → `trace <entry-symbol>` → `call-graph <entry-symbol>` → `code <entry-symbol>` → `surface <module>`.
-
-**Find DRY and de-bloat wins:** `health` → `dead` → `wrapper-candidates` → `passthrough-candidates` → `stale-abstractions` → `similar-files` → `similar-chains` → `similar-signatures` → `extract-candidates`.
-
-When recommending a command sequence, name the language and say why these commands are highest-signal for it — don't just list commands.

package/skills/scip-improve/SKILL.md

@@ -1,56 +0,0 @@
----
-name: scip-improve
-description: Use when edits should actually be made: fix confirmed cleanup findings batch by batch, consolidate a drifted twin into one canonical helper, implement a named maintainability mechanism, extract a React hook or Vue composable, move files to fix locality, or bring AGENTS.md/standards/docs back in sync with code. Requires findings already confirmed — audit first if they are not. For reducing one symbol's cognitive complexity, use `complexity-cleanup`; for deciding where a boundary belongs at design time, use `decomposition`.
-commands:
-  - template: "scip-query cleanup-plan --verify"
-    when: "Build compiler-checked deletion batches from confirmed dead-code findings."
-  - template: "scip-query cleanup-apply --verified --batch <n> --dry-run"
-    when: "Apply one already verified cleanup batch."
-  - template: "scip-query diff-gate"
-    when: "Gate each implemented improvement slice before declaring it complete."
----
-
-## Purpose
-
-This skill edits the working tree. It does not discover findings — it acts on
-findings someone already confirmed: a cleanup-plan batch, a twin-drift group,
-a maintainability register entry, a React/Vue duplicate or extraction
-candidate, a directory move ledger, or a doc-drift worklist. If nothing has
-been confirmed yet, run the matching scenario in `scip-audit` and come back
-with its evidence and disposition.
-
-## Ground rules, every scenario
-
-- Work in small, independently verifiable batches or slices — one verified deletion batch, one migration slice, one twin group, one register entry. Never apply everything unattended.
-- State the plan before editing: what's confirmed, the evidence, the intended change, how you'll verify it.
-- Re-derive evidence from current `scip-query` output, not from memory or the stale text you're replacing.
-- After every applied change, run the routed postchecks in the `scip-verify` skill, in addition to whatever narrow rerun this scenario names.
-- Load command mechanics from `_shared` first; this file only names the commands each scenario needs and what to do with their output.
-
-## Triage
-
-| Situation | Do this | Reference |
-|---|---|---|
-| Fix confirmed cleanup findings, raise health, "keep cleaning" | `health` → `cleanup-plan --verify` → preview then apply one `cleanup-apply --verified --batch <n>` in a loop | `references/cleanup-batches.md` |
-| AGENTS.md/CLAUDE.md/standards/command docs are stale or cite moved code | `doc-drift` → `outline`/`trace`/`code` per doc → rerun `doc-drift` | `references/doc-reconcile.md` |
-| Same-name/near-name functions diverged, one-sided fix, drifted threshold | `twin-drift --full` → classify → consolidate → rerun `twin-drift` | `references/twin-drift.md` |
-| Implement a confirmed maintainability register entry (hidden policy, thin wrapper, dead re-export) | `extract-candidates` / `passthrough-candidates` / `wrapper-candidates` / `stale-abstractions` / `redundant-reexports` to confirm, then implement the disposition | `references/maintainability-mechanism.md` |
-| Extract a React hook/component or Vue composable/component | cross-check confirmed candidates, classify reuse/extract/split, extract | `references/frontend-extraction.md` |
-| Move files to fix locality, declare/close an architecture boundary | `locality-candidates --full` → migration slice → boundary config → postchecks | `references/directory-moves.md` |
-
-## Owned commands
-
-`cleanup-apply`, `cleanup-plan`, `twin-drift`, `doc-drift`, `locality-candidates`, `extract-candidates`, `passthrough-candidates`, `wrapper-candidates`, `redundant-reexports`, `stale-abstractions` — each has a worked scenario in the references above; none should be run without reading the reference's evidence caveat first (several of these detectors are exploration-only with near-zero precision on codebases with intentional layering).
-
-
-<!-- BEGIN GENERATED SKILL COMMANDS -->
-## Commands for this skill
-
-| Command | Purpose | Returns | Coverage | When |
-| --- | --- | --- | --- | --- |
-| `scip-query cleanup-plan --verify` | Ordered, batched deletion plan: graph-fact dead code plus the cascade candidates it unlocks | ordered cleanup batches, evidence, and optional verification outcomes | `bounded` | Build compiler-checked deletion batches from confirmed dead-code findings. |
-| `scip-query cleanup-apply --verified --batch <n> --dry-run` | Apply a compiler-verified cleanup-plan batch to the working tree | applied files, deletions, verification, and refusal reasons | `bounded` | Apply one already verified cleanup batch. |
-| `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` | Gate each implemented improvement slice before declaring it complete. |
-
-Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
-<!-- END GENERATED SKILL COMMANDS -->

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

@@ -1,4 +0,0 @@
-interface:
-  display_name: "SCIP Improve"
-  short_description: "Apply verified fixes to the working tree"
-  default_prompt: "Use $scip-improve to apply confirmed findings as real edits, batch by batch, with verification between batches."

package/skills/scip-improve/references/cleanup-batches.md

@@ -1,53 +0,0 @@
-# Cleanup batches
-
-Use when the user asks to fix cleanup findings, raise health, keep cleaning, continue after setup, or work until no safe confirmed cleanup remains. The target is not a higher health score for its own sake — it's fixing confirmed issues that make the codebase harder to understand, verify, or change.
-
-## Before editing
-
-If cleanup findings have not been swept and confirmed yet, run the cleanup
-scenario in `scip-audit` first. Then report a markdown block before touching
-any code:
-
-- current score from `scip-query health`
-- the first confirmed batch: finding, evidence, planned fix, verification plan
-- remaining signals with status
-
-## Priority order
-
-Work top to bottom, one item at a time:
-
-1. Compiler-verified deletion batches (`cleanup-plan --verify`).
-2. Incomplete migrations (`incomplete-migration --json --full`) and recent duplicate echoes (`duplicate-bodies --json --full`, exact small-body echoes).
-3. Unused params/imports, dead symbols, isolated symbols.
-4. Broken or stale docs, config validation issues, missing co-change partners.
-5. Thin wrappers, passthroughs, stale abstractions, speculative generality.
-6. Frontend component/hook/composable duplication and large-view pressure.
-7. Directory architecture and maintainability repairs — only when evidence is strong and blast radius is bounded.
-
-## The loop
-
-Repeat until stopping:
-
-1. Preview one verified deletion batch with `scip-query cleanup-apply --verified --batch <n> --dry-run`. Confirm the exact files, symbol ranges, LOC, and verifier match the intended batch; then run the same command without `--dry-run` to apply it. Otherwise make one small targeted refactor for the next prioritized item.
-2. Run the narrow project check for the touched behavior (tests/typecheck scoped to what changed).
-3. Run `scip-query health`.
-4. Invoke the `scip-verify` skill.
-5. If `docs/scip-query/health-dossier.md` exists (or a custom `--dossier-dir` was used), refresh it by rerunning `scip-query setup --json` with the same `--dossier-dir` if one was used.
-6. Pick the next highest-priority confirmed item and repeat.
-
-Only use `scip-query cleanup-apply --all` with explicit user approval — never apply all batches unattended by default.
-
-## Stop when
-
-- Only intentional, false-positive, blocked, or unconfirmed items remain.
-- The next improvement would require a product/API/ownership decision.
-- A missing toolchain prevents trustworthy verification.
-- Further work would amount to broad redesign, not bounded cleanup.
-
-## Between passes
-
-After a cleanup pass, run `scip-query health --write-baseline` to snapshot finding identities. At the start of the next pass, compare against it with `scip-query health --baseline`.
-
-## Closeout report
-
-Starting and final health scores, batches applied, important files changed, verification commands run, remaining accepted or blocked items, and the highest-value follow-up.

package/skills/scip-improve/references/directory-moves.md

@@ -1,53 +0,0 @@
-# Directory moves
-
-Use to move files to fix locality or to close a dependency rule once the
-directory scenario in `scip-audit` has produced a target structure or move
-ledger. If there is no reviewed target structure yet, run that scenario first
-— this reference starts from its output and never invents a target structure
-on its own.
-
-## Find and confirm the move
-
-Run `scip-query locality-candidates --full` for directory-locality and ancestry candidates from consumer ownership (symbols, current homes, consumer locality, suggested homes). Cross-check current placement with `scip-query system <scope>` (files, exported symbols with line ranges, internal deps, reverse deps).
-
-Concepts that decide whether a move is safe:
-
-- **Ownership boundary** — a folder, package, module, or convention grouping code around one stable responsibility.
-- **Forbidden edge** — an actual cross-boundary dependency rejected by an explicit project rule. Directory distance or an unusual import alone does not make an edge forbidden.
-- **Reciprocal dependency** — traffic in both directions between two boundaries. It's a review signal that the boundaries exert mutual pressure, not proof that either import is wrong.
-- **Migration slice** — the smallest set of file moves and import updates that can be verified independently.
-
-Rules: separate review from migration — don't move files unless asked. Preserve broad boundaries when evidence shows they're intentional. Don't reward a generic "shared" boundary/directory unless the shared concept has a name, an owner, and cross-boundary consumers. Prefer small verified moves over large speculative reorganizations. Configure descriptive boundaries before closing dependency rules.
-
-Before editing a slice, state: the files to move, the imports/exports/tests/docs to update, the expected verification, and the rollback risk.
-
-## If boundaries themselves are changing
-
-Add mature boundary path patterns to `.scipquery.json` under `architecture.boundaries` **without** `allowedDependencies` rows first, e.g.:
-
-```json
-{ "architecture": { "boundaries": [
-  { "name": "domain", "paths": ["src/domain/**"] },
-  { "name": "runtime", "paths": ["src/runtime/**"] }
-] } }
-```
-
-Then run `scip-query config-validate`, then `scip-query architecture`.
-
-An `allowedDependencies` row is closed: an outgoing target omitted from a present row is forbidden, but a missing row makes no dependency claim at all. Example: `{ "architecture": { "boundaries": [...], "allowedDependencies": { "domain": [], "runtime": ["domain"] }, "requireAcyclic": true } }`. For each closed row, record the evidence for its intended direction. Never copy the current dependency graph into the allow-list merely to obtain zero findings; leave emerging or disputed rules undeclared rather than closing the row prematurely.
-
-When repairing a boundary cycle, inspect the least-broad edge inside it first, then decide whether the fix is a move, a dependency inversion, a named shared contract, a boundary merge, or a policy correction.
-
-## Ratcheting enforcement on a large repo
-
-Before enabling architecture regression enforcement on an existing codebase, review the direct findings with `scip-query drift --architecture` and record reviewed existing debt with `scip-query health --write-baseline`. The baseline records stable architecture identities by boundary pair, not by whichever example file happens to sort first. Commit `.scipquery-baseline.json` together with `.scipquery.json`.
-
-The default `diff-gate` architecture check compares only architecture identities and does not run every health detector; `diff-gate --baseline` is the opt-in full health ratchet and does not duplicate architecture findings. A missing baseline causes the architecture gate to report that enforcement is not enabled — it does **not** silently treat the current dependency graph as accepted.
-
-## After moving the slice
-
-Run `scip-query incomplete-migration`, `scip-query recent-duplicates`, and `scip-query co-change <moved-file-or-config>`, plus the project's tests or typecheck for the affected workspace.
-
-If `.scipquery.json` locality changed, also run `scip-query config-validate`, `scip-query locality-candidates --full`, `scip-query architecture`, `scip-query drift --architecture`, and `scip-query diff-gate`.
-
-Then invoke `scip-verify`. The implementation is complete only when imports, tests, locality signals, and verification are all checked.

package/skills/scip-improve/references/doc-reconcile.md

@@ -1,30 +0,0 @@
-# Doc reconciliation
-
-Use for stale standards, broken file references, docs that cite moved code, agent guidance, or normative contradictions between documentation and implementation. Only reconcile living docs — documentation agents or maintainers use to make present-day changes: AGENTS.md, CLAUDE.md, standards, command docs, workflow docs. Do not reconcile archival records (dated plans, ADRs, reports); list them in `.scipquery.json` under `docs.snapshotPaths` so `doc-drift` excludes them with a labeled exclusion instead of resurfacing them every sweep.
-
-The core distinction driving every edit:
-
-- **Descriptive claims** say what the code currently does or where it lives. Update them when code moves.
-- **Normative claims** say what code must or should do. If code violates one, fix the code or escalate the contradiction — never weaken the standard silently to match drifted code.
-
-## Step 1 — Build the worklist
-
-Run `scip-query doc-drift --full` for the ranked worklist (document paths, coupled code subjects, history evidence), plus `scip-query doc-drift <doc-or-tree>` for anything scoped. Prioritize broken references first, then highest staleness, then the docs agents read most. Done only when each target doc is selected for a current-use reason.
-
-## Step 2 — Reconcile one doc
-
-For each doc: `scip-query doc-drift <doc>`, `scip-query outline <subject-file>` for its current shape, `scip-query system <module>` for the surrounding module, `scip-query trace <symbol>` for every symbol the doc mentions, `scip-query code <symbol>` to re-derive any snippet from current source (never from memory or the stale text). Use git history only to understand why a subject changed, never as a substitute for current code evidence.
-
-- Fix broken references by finding the current code or deleting the obsolete claim.
-- Rewrite stale descriptive claims from the evidence just gathered.
-- Record normative contradictions instead of changing standards to bless drifted code.
-
-Done only when every edited claim is supported by evidence gathered in this session.
-
-## Step 3 — Verify
-
-Rerun `scip-query doc-drift <doc>`. If the documentation change is part of a codebase diff, invoke `scip-verify`. Don't claim reconciliation is done until `doc-drift` has been rerun. Done only when staleness drops to zero or the remaining contradiction is explicitly reported.
-
-## Step 4 — Report
-
-Staleness before and after, broken references fixed, claims updated, normative contradictions surfaced, and docs recommended for deletion.

package/skills/scip-improve/references/frontend-extraction.md

@@ -1,39 +0,0 @@
-# React/Vue extraction
-
-Use to extract a React hook/component or a Vue composable/component once the
-frontend scenario in `scip-audit` has produced confirmed candidate pairs. If
-nothing is confirmed yet, run that scenario first, then cross-check, then act.
-
-- A **component duplicate candidate** is a pair or group of rendered structures repeating the same user-facing arrangement, controls, states, props/bindings, or data-presentation shape enough that a shared component may reduce drift.
-- A **hook candidate** (React) / **composable candidate** (Vue) is a pair or group of behaviors repeating the same state lifecycle, effects, requests, validation, persistence, or derived-data policy enough that a shared hook/composable may preserve behavior better.
-- **Large component/view pressure** means one component, SFC, or linked view file contains several kinds of knowledge that change for different reasons — a large file or style block is pressure, not proof, by itself.
-
-## Scan (only if not already done)
-
-React: `scip-query react-component-duplicates`, `react-hook-candidates`, `react-large-component-pressure`, `recent-duplicates`, `health` — all `--scope <scope> --full`, uncapped.
-
-Vue: same shape, using `vue-component-duplicates`, `vue-composable-candidates`, `vue-large-view-pressure`. Before scanning, when component references, imported composables, script blocks, or linked external scripts matter, run `scip-query augment-vue --project <path-to-tsconfig>` to add compiler-resolved Vue SFC references via Volar — Vue needs this step; React doesn't.
-
-Record scope, counts, and uncapped/full status.
-
-## Cross-check before acting
-
-Use `scip-query outline <file>`, `deps <file>`, `rdeps <file>`, `similar-files --scope <scope>`, and either `scip-query similar <closest-existing-component-or-hook>` (React) or `scip-query recent-duplicates --scope <scope> --full` (Vue) to validate each candidate. Classify every top candidate as reuse, extract, split, skip, or blocked:
-
-- Component-duplicate-only → look for a shared presentational component or existing reuse.
-- Hook/composable-candidate-only → look for shared state lifecycle, effects, requests, validation, persistence, or derived-state policy.
-- Both overlap → look for a feature-level concept that needs both a component boundary and a hook/composable boundary.
-- Large-component/view-only → split by reason to change, not by line count.
-
-## Act
-
-Prefer reuse over extraction. Extract a component for repeated UI/template structure, props, slots/children, states, or design-system composition. Extract a hook for repeated state, effects, requests, subscriptions, memoized derivations, callbacks, or persistence; extract a composable for the Vue equivalent — repeated state, lifecycle, requests, validation, persistence, derived data, or event policy. Keep essential domain-specific variation at the call site.
-
-Don't:
-- Create boolean-soup APIs or wrapper components/composables with no policy as a side effect.
-- Treat shared design-system primitives, icons, labels, route names, test IDs, or CSS utilities alone as sufficient evidence for a duplicate/hook/composable claim.
-- Extract a shared hook or composable from templates that merely look similar but carry different domain lifecycles — that similarity may justify a shared presentational component, never a shared hook/composable.
-
-## Verify and report
-
-Invoke `scip-verify` and run its React or Vue postcheck rows, plus the applicable extraction, duplicate, parameter, wrapper, passthrough, and stale-abstraction checks. Work is complete only when the acted-on candidate pairs disappear, weaken materially, or are explicitly accepted as essential variation. Report: executive read, command evidence, candidate groups, recommended action taken, post-change proof, and remaining accepted variation.