scip-query 0.19.5 → 0.19.8

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "SCIP Explore"
-  short_description: "Trace systems with SCIP evidence"
-  default_prompt: "Use $scip-explore to understand this system end to end with SCIP-backed code evidence."
+  short_description: "Understand a system with SCIP evidence"
+  default_prompt: "Use $scip-explore to understand this system end to end with SCIP-backed code evidence before editing it."

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

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

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

@@ -0,0 +1,56 @@
+---
+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 --json"
+    when: "Build compiler-checked deletion batches from confirmed dead-code findings."
+  - template: "scip-query cleanup-apply --verified --batch <n>"
+    when: "Apply one already verified cleanup batch."
+  - template: "scip-query diff-gate --json --compact"
+    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` → `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 --json --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 --json --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 --json` | 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>` | 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 --json --compact` | 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

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

@@ -0,0 +1,53 @@
+# 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 --json`
+- 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. Apply one verified deletion batch — `scip-query cleanup-apply --verified --batch <n>` against the plan from `scip-query cleanup-plan --verify --json` — or 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 --json`.
+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

@@ -0,0 +1,53 @@
+# 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 --json --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 --json`, then `scip-query architecture --json`.
+
+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 --json --full`, `scip-query architecture --json`, `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

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

@@ -0,0 +1,39 @@
+# 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 --json`, 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 --json` (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.

package/skills/scip-improve/references/maintainability-mechanism.md

@@ -0,0 +1,43 @@
+# Implementing a maintainability mechanism
+
+Use to implement a confirmed maintainability opportunity: a register or atlas
+entry that names a hidden policy, an unnamed lifecycle, or scattered concepts,
+and proposes a disposition. Maintainability is the degree to which real code
+units let a maintainer understand, verify, and change behavior without
+rediscovering hidden knowledge. If there is no confirmed register entry yet,
+run the maintainability scenario in `scip-audit` first — this reference starts
+from its output.
+
+## Vocabulary you need to act correctly
+
+- **Concept boundary** — the line around code units that exist for one reason to change.
+- **Hidden policy** — a rule for choosing among several plausible behaviors that lives in local branches, comments, conventions, or caller folklore instead of a named mechanism.
+- **Lifecycle** — a repeatable sequence of states or steps that makes a result valid.
+- **Essential variation** — difference that must remain because the real units differ: language grammars, user-visible APIs, runtime environments, compatibility boundaries. **Accidental variation** — difference in code shape that doesn't correspond to any of those. Preserve the former; remove the latter.
+- **System compression** — replacing several mechanisms that perform the same role, policy, lifecycle, or surface job with fewer named mechanisms, preserving behavior.
+- **Unifying definition** — the single essential trait that makes several code sites one concept. A merge, extract, or generate action is only justified when you can state this trait and it covers every cited site; if it doesn't, the variation is essential and those sites must not be consolidated.
+
+Ground every action in files, symbols, references, call graphs, dependencies, surfaces, and blast radius — never opinion. Name concrete referents before naming a smell. Don't chase health scores; detector counts are clues, not objectives. Only add an abstraction when it removes hidden policy, names a lifecycle, enforces a rule, or reduces concept count — never for its own sake. Prefer deletion, inlining, merging, generation, or enforcement of an existing mechanism before introducing a broad new framework.
+
+## Priority when several confirmed entries compete
+
+Rank by severity tier, most severe first: (1) hidden correctness or evidence policy spread across modules, (2) a repeated lifecycle/pipeline with no owner, (3) public surface exposing accidental internals, (4) a large module with unrelated reasons to change, (5) tests that encode incident history without contract vocabulary, (6) adapter families with repeated capability/fallback shapes, (7) suppression comments documenting architecture decisions instead of exceptions, (8) thin wrappers/passthroughs that don't buy clarity. Reject and don't act on smells that are aesthetic, unverifiable, or false compression.
+
+## Confirming a candidate before you touch code
+
+- `scip-query extract-candidates` finds heuristic extraction candidates from isolated callee clusters. When the register calls for extracting a shared helper, run this to confirm the callee cluster, then read every cited site to check the unifying definition actually holds.
+- `scip-query passthrough-candidates` finds heuristic passthrough candidates that forward to one callee. When the disposition is inline or delete, run this to confirm the passthrough is real before removing it.
+- `scip-query wrapper-candidates` and `scip-query stale-abstractions` find, respectively, single-consumer wrappers and 0–1-consumer abstractions — both have near-zero precision on codebases with intentional layering or ambient types. Treat every hit as exploration, never a finding; run them only after the main sweep is exhausted; never act on a hit without reading the cited code first, and confirm real consumer counts with `refs`/`surface` before deciding a disposition.
+- `scip-query redundant-reexports` finds barrel re-exports that nobody imports through. When the disposition is delete, confirm no import path actually uses the barrel, then remove the re-export and update any doc or index that referenced it.
+
+## Dispositions
+
+merge, delete, inline, extract, generate, enforce, supersede, defer, skip. Every merge/extract/generate action must carry its unifying definition and its strongest dissenter — the cited site most likely to differ essentially — plus evidence that the dissenter doesn't actually differ essentially. If a dissenter survives review (it really does differ essentially), the entry's disposition becomes skip with reason "essential variation," but the dissenter stays recorded either way.
+
+## Implement
+
+Implement the smallest named mechanism that matches the real concept. Keep essential variation near the adapter or domain code that knows it, not buried inside the new mechanism.
+
+## Verify and report
+
+Run focused tests, then the routed postchecks from `scip-verify`. The final report states the smell addressed, the mechanism introduced or removed, what was deliberately not compressed, and the verification results.

package/skills/scip-improve/references/twin-drift.md

@@ -0,0 +1,35 @@
+# Twin drift
+
+Use when the same concept exists in more than one place under the same or a near-name and the bodies have silently diverged — same-name or near-name functions across files with diverged bodies, drifted policy thresholds, one-sided fixes, or consolidating a duplicated concept into one canonical helper.
+
+A twin drift group is a same-leaf-name family of callables spanning at least two files whose normalized-token bodies are neither identical (that's `duplicate-bodies`' job) nor unrelated (a homonym like `render` or `parse`), but partially overlapping — a concept copied once and edited independently in only some copies. "Near-name" means case-insensitive match, or edit-distance ≤ 2 for names of 8+ characters.
+
+## Detect
+
+Run `scip-query twin-drift --json --full` to surface every DIVERGENT and near-name group in scope; scope it with `-s/--scope <path>` when the review should be bounded. Cross-check against `scip-query duplicate-bodies --json --full` — IDENTICAL groups belong there, not here; don't re-report them. Homonyms (similarity below `--min-similarity`, default 0.3) are noise — skip them unless `--include-homonyms` was explicitly requested. Record group count, member count, and `maxDivergence` per group. Done only when every group in scope is enumerated with its relationship (divergent vs. suppressed homonym).
+
+## Classify
+
+For every DIVERGENT group, read each member's body with `scip-query code <symbol>`, starting from the group's `firstDivergentTokens` field to locate where the bodies diverge. Assign exactly one label with a one-line reason:
+
+- **Intentional variation** — the domains genuinely differ (e.g., a React-specific vs. Vue-specific structural comparator branching on framework-specific checks). Essential variation stays; record the reason.
+- **Drifted policy** — one policy (a threshold, a normalization rule, an edge-case guard) only some copies received when it last changed. This is a bug: pick the correct value and propagate it, or extract the policy into one named function/constant.
+- **One-sided fix** — one copy was bugfixed or hardened and its twin(s) weren't. This is a bug: apply the same fix to every member, or consolidate.
+
+Done only when every DIVERGENT group has one of the three labels with its reason.
+
+## Consolidate
+
+Pick the canonical member by comparing consumer counts via `scip-query refs <symbol-in-file-A>` and `scip-query refs <symbol-in-file-B>` — prefer the member with more consumers, or the one in the more general/shared location on a tie. Extract or move the canonical body to one exported helper and update the other members to call it, or delete them outright if they were pure duplication under a different name for caller convenience. Preserve classified-essential variation as a parameter or a thin caller-side branch, not a second copy of the whole body. For intentional-variation groups, don't force consolidation — record the reason in a comment near one of the members so the next `twin-drift` run and the next reader both see it was considered.
+
+Done only when every DIVERGENT group is either consolidated (old copies gone or forwarding) or has a recorded reason it stays separate.
+
+## Verify
+
+Rerun `scip-query twin-drift --json --full` to confirm consolidated groups no longer appear as DIVERGENT, then run the routed postchecks from `scip-verify`. The twin-partner check inside `diff-gate` is advisory and never blocks the gate by itself — but a finding there on your own diff means you've reproduced the exact defect class this skill exists to catch; treat it as a signal to run this workflow, not just to suppress the finding. Fix it or explicitly accept it before finishing.
+
+Done only when `twin-drift` shows no unclassified DIVERGENT groups in scope and any `diff-gate` findings are resolved or explained.
+
+## Report
+
+Scope, groups found (total / divergent / suppressed homonyms), each divergent group with its classification and action taken, and the verification results of `twin-drift --json --full` and `diff-gate --json`.

package/skills/scip-plan/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: scip-plan
+description: Use before, during, AND after non-trivial work: plan a change, migration, or refactor; assess what breaks when changing a public export, module boundary, schema, route, CLI command, config field, generated artifact, signature, or documented behaviour; conduct a multi-phase program and review a delegated agent's work mid-flight; plan a performance campaign; scaffold a TLA+ model before implementing, and trace-check it against the real system afterward. Distinct from the `review` skill, which reviews a finished branch or PR against coding standards and the originating spec — this one oversees a program you are conducting.
+commands:
+  - template: "scip-query plan-context <target>"
+    when: "Anchor the current flow, consumers, reuse options, and change risks."
+  - template: "scip-query refs <symbol>"
+    when: "Complete or narrow the direct consumer set for a planned symbol change."
+  - template: "scip-query affected <symbol> --json"
+    when: "Measure transitive impact when the change is not consumer-local."
+---
+
+# scip-plan
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | definitions and references; callers and callees; dataflow producers and consumers; backward and forward slices; affected symbols; change-surface risk; dependencies and reverse dependencies; module files and exports; external surface use; complexity; churn; co-change partners; active suppressions | `bounded` | Anchor the current flow, consumers, reuse options, and change risks. |
+| `scip-query refs <symbol>` | Find all files referencing a symbol | referencing file paths; reference line numbers grouped by file | `bounded` | Complete or narrow the direct consumer set for a planned symbol change. |
+| `scip-query affected <symbol> --json` | Transitive closure of symbols that could break if this symbol changes | affected symbol identities, files, and traversal depths | `bounded` | Measure transitive impact when the change is not consumer-local. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Purpose
+
+Plan and conduct work: a single non-trivial change, public-surface impact, a multi-phase program carried end to end with verification at each handoff (including reviewing a delegated agent's work in flight), a benchmark-driven optimization campaign, and TLA+ modelling both before implementation and as post-implementation trace-conformance.
+
+Shared mechanics (lookup tips, command families, postchecks, subagent-briefing text, general command catalogue) live in `../_shared/SKILL.md` — load it only when this skill's own shortlist is insufficient.
+
+## Pick the mode first
+
+| Situation | Do this |
+|---|---|
+| One non-trivial change, refactor, migration, or bug fix | Ordinary-mode scenario below |
+| The change touches a security boundary, money, a destructive/irreversible op, a persistent-data migration, shared-state concurrency, a broad public API, or an unrollback-able rollout — or the user asks for the rigorous version | `references/high-assurance.md` |
+| You're about to edit a public export, route, schema, CLI command, config field, generated artifact, or documented behavior, and need to know what breaks | `references/api-impact.md` |
+| You're running a multi-phase program: writing an executable plan, delegating steps, reviewing a subagent's work mid-flight, or carrying a change end to end | `references/conductor.md` |
+| You need something faster and must prove the speedup with measurements | `references/hyper-optimization.md` |
+| You need a TLA+ model of a risky protocol, before or after implementation | `references/tla-model.md` |
+
+Picking the mode matters: running the high-assurance certificate on routine work is how planning becomes a tax people route around. When genuinely unsure whether a change needs a heavier mode, ask rather than defaulting up.
+
+## Scenario: plan a single non-trivial change (ordinary mode, the default)
+
+Apply `_shared`'s freshness gate once before citing the first graph fact; let an active watcher handle refreshes and use manual reindex only as the documented fallback. Then run `scip-query plan-context <target>` — the single anchoring call for planning. Its composite return already includes definitions, references, callers, callees, dataflow producers/consumers, forward and backward slices, affected symbols, change-surface risk, dependencies and reverse dependencies, module exports, external surface use, complexity, churn, co-change partners, and active suppressions, so the job is to interpret this composite rather than rebuild a proof system on top of it.
+
+Reach for a second command only when a section `plan-context` returned came back bounded (not complete) or the target wasn't indexed: `scip-query refs <symbol>` to enumerate consumers in full, `scip-query affected <symbol>` for the transitive blast radius when the change isn't consumer-local, `scip-query code <symbol>` to read the source behind a behavior claim before writing it into the plan.
+
+Write the plan to `docs/plans/YYYY-MM-DD-<short-name>.md` with these sections:
+
+- **Goal** — what the user is trying to accomplish, and what done looks like for them.
+- **Current Flow** — the affected path from entry point to observable effect, in prose, with evidence behind each claim; if current behavior can't be described end to end, the change isn't ready to make.
+- **Affected Consumers** — who calls/imports/reads the changed code and what breaks if the contract shifts; state explicitly whether the list is complete or bounded — a capped list presented as complete is worse than one flagged as bounded.
+- **Reuse Decision** — for every new helper/wrapper/type/parameter/flag/component/hook/module, name what it could have extended instead and why extension loses. New parallel code with no reuse decision is the single most common defect this skill exists to prevent.
+- **Slices** — ordered implementation steps, each naming its files/symbols, the behavior change, and the validation (a test, command, or specific manual check) that proves it. A slice with no validation is a wish.
+- **Risks and Unknowns** — what could go wrong, what couldn't be established, and any rollout constraint; keep unknowns explicit rather than rounding them to assumptions.
+
+The plan is done only when: the entry-to-effect path is described and evidenced, every affected consumer is assigned to a slice or explicitly out of scope, every new unit has a reuse decision, every slice has validation, and unknowns are written down rather than resolved by guessing. Then implement in the smallest coherent slice and run `scip-verify` when the change lands.
+
+## Owned command quick-reference
+
+`bench`, `work-audit` → performance campaigns, see `references/hyper-optimization.md`.
+`tla`, `tla scaffold`, `tla verify`, `tla instrument`, `tla trace-check`, `tla fetch-tools` → model scaffolding and conformance, see `references/tla-model.md`.
+
+Everything else used above (`plan-context`, `refs`, `affected`, `code`, `surface`, `co-change`, `doc-drift`, `diff-gate`, `health`, `call-graph`, `complexity`, `change-surface`, ...) is general catalogue — see `../_shared/SKILL.md` for the full vocabulary.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Plan & Conduct"
+  short_description: "Plan and conduct work with SCIP evidence"
+  default_prompt: "Use $scip-plan to plan this change, assess what it breaks, and conduct it through to verified completion."

package/skills/scip-plan/references/api-impact.md

@@ -0,0 +1,19 @@
+# Public-surface impact
+
+Use before changing anything another process or person depends on: a callable, export, route, schema, config field, CLI command, generated artifact, or documented behavior. Its defining trait: a local edit can force coordinated consumer, docs, tests, or migration changes outside the implementation file.
+
+## Scenario: assess what breaks before editing a public surface
+
+**Step 1 — identify the actual surface.** Run `scip-query surface <module-or-package>`, `scip-query outline <file>`, `scip-query trace <symbol-or-command>`, `scip-query code <symbol-or-command>`, and `scip-query hierarchy <symbol> --json`. Done only when the real surface is named as one of: member, class, module, package, route, schema, command, or config field.
+
+**Step 2 — find consumers.** Run `scip-query refs <symbol>`, `scip-query fan-in <symbol>`, `scip-query rdeps <file>`, `scip-query affected <symbol> --json`, and `scip-query change-surface <file> --json --full`. Record direct consumers separately from transitive consumers. Done only when direct breakage and regression blast radius are both known.
+
+**Step 3 — find hidden partners.** Run `scip-query co-change <file> --json --full` (files historically coupled without a dependency edge), `scip-query doc-drift --json --full` (docs describing the surface), `scip-query similar <symbol> --json --full`, and `scip-query similar-files <file> --json --full`. Docs, generated files, tests, and config count as part of the API when they describe or enforce the surface. Done only when docs, generated files, fixtures, sibling APIs, and hand-synchronized partners are accounted for or ruled out.
+
+**Step 4 — choose the migration shape.** Pick one of: compatible extension, two-step migration, breaking coordinated change, or an adapter shim for external consumers/compatibility windows. Prefer backward-compatible migrations when consumers are broad or external. Reject speculative new parameters or empty wrappers using `scip-query unused-params --json --full`, `scip-query wrapper-candidates --json --full`, and `scip-query passthrough-candidates --json --full`. Done only when the migration shape explains deploy order, rollback, and compatibility risk.
+
+**Step 5 — write the plan and verify.** Plan template: Surface; a Consumer dispositions table (Consumer | Kind: direct/transitive/doc/config/test | Disposition: unchanged-safe/update/shim/defer); Required co-changes; Migration; Verification (targeted tests, `scip-query diff-impact --json`, `scip-verify`, `scip-query doc-drift --json --full` if docs changed, `scip-query config-validate` if config changed). Every consumer returned by refs/affected must appear as a row — a blank disposition means the analysis is unfinished. Non-indexed consumers (SQL, fixtures, dynamic strings, external callers) must be checked with `rg` and rowed the same way as indexed consumers.
+
+After editing, run the routed checks from `_shared` and invoke `scip-verify`. The workflow is complete only when direct consumers, docs/config partners, and scip-verify have all been checked.
+
+Final report shape: API impact (low/medium/high); Surface changed; Consumers; Migration plan; Co-changes; Verification; Remaining risk.

package/skills/scip-plan/references/conductor.md

@@ -0,0 +1,41 @@
+# Conducting a multi-phase program
+
+This governs running a program of work — planning, delegation, review, closure — across multiple steps, not how to write a single change plan (use the main SKILL.md's ordinary-mode scenario, or `references/high-assurance.md`, for that). Act like a skeptical principal engineer.
+
+Key commands: `scip-query plan-context <target>` anchors each phase's step before delegating it; `scip-query diff-gate --json` verifies a handoff before accepting it and before closing the program; `scip-query health --json` pre-registers or checks a program-level health benchmark.
+
+## The three laws
+
+1. **A green result you have never seen fail is unverified.** This applies to tests, gates, reports from other agents, and your own checks (the integrity scenario in `scip-audit` applies the same law to code, where available).
+2. **A plan is a contract for a less-capable executor, not a note to self.** If a competent-but-uninspired agent could not execute a step without guessing, the step is not finished being written.
+3. **Nothing is silent.** Every finding, deviation, and shortcut must be either fixed or written down with a reason someone else would accept. 0% silent is the invariant — "fixed everything" is not.
+
+## Scenario: write the program plan
+
+State DONE MEANS falsifiably in the Goal — a command someone can run and a result they can check, not an aspiration. Pre-register acceptance benchmarks before any work: measure the current number (test count, timing, finding count, proof line), write it in the plan, and state the target number; work that cannot move a pre-registered number is scope to question.
+
+Every plan step carries five fields: a file anchor with verified current behavior (cite how you know), the exact change, the validation command with expected output, a testability design (pure core, injected effects), and why this step is safe in this order. "Update X" with no current/target behavior is a wish, not a step.
+
+Order phases by information gain and risk: blockers and evidence-integrity first, cheap discriminating probes before expensive builds, measurement before optimization, and anything not yet decided by the human becomes a GATED phase the executor must not start. Infrastructure that later steps inherit (a labeling choke point, a shared helper layer) must land before the features that need it. Flag one-way doors with their migration path, and keep an explicit DEFER list so cut scope is visible instead of forgotten.
+
+Working agreement to include in the plan: ONE COMMIT PER STEP — bisectability is non-negotiable, and phase-level commits hide which step broke. Gate commands must be the FULL gate set the repo defines per phase — tests, typecheck, lint/format, and build — not just focused tests, because focused tests hide cross-phase regressions and omitting the linter is how red mains ship. Include regeneration duties and a deviation protocol: if source contradicts an anchor, BLOCKED-note it and continue; never improvise silently.
+
+## Scenario: delegate and review a handoff
+
+Delegate breadth, keep judgment: fan out mechanical/scoped work to subagents, but personally own anything requiring taste, cross-cutting context, or the final word on "is this real." Concurrent agents must get disjoint write scopes, named in their briefs; if a collision happens anyway, stop racing, apply-verify-commit atomically in one action, and re-sequence to a single writer.
+
+Never accept a report at face value — reproduce its evidence. On every handoff, choose the minimal discriminating probe (the one command most likely to expose the report being wrong: a mutation input, a hand count, the benchmark number) and run it yourself; a report verified only by reading it is not verified. Loop until `scip-query diff-gate --json` is quiet: fix, re-run the discriminating probe, re-run the gate, and only then move on.
+
+Verify your verifier: a gate check that cannot fail is no gate (e.g. a lint grep that only matches one linter's output, a diff-gate run on a clean tree, a test suite that skips the new path) — prove the check catches a planted failure once before trusting its green. After any "all green," ask what that check does NOT cover (eslint vs prettier; unit vs integration; clean-tree vacuity).
+
+## Git and commit discipline
+
+Never run `git checkout`/`restore`/`stash` on a tree with uncommitted work, yours or anyone's; revert probe edits by targeted deletion instead, and if source is lost, check `dist/*.map` sourcesContent before panicking. Commit working states early and surgically using explicit paths, never `add -A` on a shared tree; an unbisectable pile of work is a liability. Make commit cadence mechanical: at every step boundary run the arithmetic check "steps completed == commits made"; if they differ, stop and commit before touching anything new. "I'll commit when it's all done" is the signature decay pattern of a long or low-effort run — in two real executions this rationalized delay led to finishing an entire plan with zero or one commit, with the deviation rationalized mid-run rather than decided; a self-check that is a count (not a feeling) prevents this rationalization.
+
+## Closing the program
+
+After the program, fold what was learned back into the durable layer (docs, skills, followups) — insight that lives only in the conversation is lost. Escalate only genuine decision points — one-way doors, scope changes, taste, spending; for everything else, decide, act, and disclose.
+
+Every conducted program and every plan written under this skill must end with a self-report checklist mapping each section above to concrete evidence: pre-registered benchmarks and their before/after values, each handoff's discriminating probe and its OBSERVED result (a probe listed but not run counts as not run), the deviation ledger, the DEFER list, and which learnings were folded back and where — so a reviewer can audit the conduct, not just the artifact.
+
+The program is complete only when: every pre-registered benchmark is met or its miss explained; every handoff probe is run and recorded; the gate is quiet on the final state; nothing is silent (every finding fixed or ledgered); and the self-report is written.