scip-query 0.10.12 → 0.12.0

package/skills/scip-query/SKILL.md

@@ -1,130 +1,114 @@
 ---
 name: scip-query
-description: Router for codebase work in scip-query-indexed projects. Use whenever exploring, planning, implementing, refactoring, extracting helpers, verifying changes, hunting duplication or bloat, fixing stale docs, or cleaning up after an AI coding session — or when unsure which scip-* skill applies. Picks the right specialist skill and the commands that must run for each phase of work.
+description: Route codebase work in scip-query-indexed projects. Use when exploring, planning, implementing, refactoring, debugging, verifying, cleaning up, reconciling docs, improving health, or when unsure which scip-* skill should own the workflow.
+commands:
+  - template: "scip-query status --capabilities"
+    when: "Before routing: confirm the index is fresh."
+  - template: "scip-query plan-context <target>"
+    when: "Default loop: anchor a plan for the routed skill."
+  - template: "scip-query diff-gate --json"
+    when: "Default loop: the loop is complete only when this passes or is explained."
 ---
 
 # scip-query Router
 
-This project is indexed by `scip-query` — compiler-resolved code intelligence.
-Your job here is only to route: identify the phase of work, invoke the right
-specialist skill, and enforce the non-negotiable checks. Do not improvise a
-workflow when a specialist skill exists for it.
-
-Before trusting graph facts, check freshness with `scip-query status --capabilities`
-or `scip-query status --json`. If the index is `fresh`, continue without
-reindexing. If it is `stale`, `missing`, or `unknown`, run `scip-query reindex`
-before using code-intelligence results. Project hooks auto-refresh stale indexes
-by default unless `.scipquery.json` sets `watch.autoRefresh: false`.
-
-## The default loop for any implementation request
-
-When the user asks you to build, change, or fix something non-trivial:
-
-1. **Plan first** — invoke `concrete-plan` (every claim in the plan must come
-   from a scip-query command, anchored by `scip-query plan-context <target>`).
-2. **Implement** the plan.
-3. **Verify** — invoke `scip-verify`, then run the post-checks that match what
-   you changed (table below).
-4. **Gate before done** — check freshness; reindex only when the index is not
-   `fresh`, then run `scip-query diff-gate --json`; fix findings or state
-   explicitly why each is accepted.
-
-## Route by phase of work
-
-| You are about to...                                                                                                | Invoke                        | Anchor commands                                                                                             |
-| ------------------------------------------------------------------------------------------------------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| Understand how something works, trace a system end-to-end                                                          | `scip-explore`                | `scip-query system <module>`, `scip-query trace <symbol>`                                                   |
-| Debug a bug, regression, failing behavior, or wrong data flow                                                      | `scip-debug`                  | `scip-query trace <symbol>`, `scip-query dataflow <symbol>`, `scip-query change-surface <file>`             |
-| Triage a bug report or issue into evidence and a fix plan                                                          | `scip-triage-issue`           | `scip-query files <term>`, `scip-query trace <symbol>`, `scip-query affected <symbol>`                      |
-| Create a visual explanation, flow map, dependency map, or HTML diagram                                             | `scip-diagram`                | `scip-query call-graph <symbol>`, `scip-query dataflow <symbol>`, `scip-query affected <symbol>`            |
-| Plan a feature, fix, or refactor                                                                                   | `concrete-plan`               | `scip-query plan-context <target>`                                                                          |
-| Assess a public API, route, CLI, config, schema, or boundary change                                                | `scip-api-impact`             | `scip-query surface <module>`, `scip-query affected <symbol>`, `scip-query co-change <file>`                |
-| Pick high-signal commands for an unfamiliar language                                                               | `scip-language-playbook`      | —                                                                                                           |
-| Benchmark indexing, command runtime, or detector performance                                                       | `scip-query`                  | `scip-query bench --json`, `scip-query bench --cold-index --include-heavy`                                  |
-| Hyper-optimize a command, workflow, indexer, detector, or app path with benchmark ledgers and alternative designs  | `scip-hyper-optimization`     | `scip-query bench --json`, `scip-query plan-context <target>`, command-specific correctness checks          |
-| Adopt or bootstrap scip-query in a repository                                                                      | `scip-adoption`               | `scip-query setup --json`, `scip-query check-deps`, `scip-query capability-matrix --json`                   |
-| Verify work you just finished (any implementation, refactor, or extraction)                                        | `scip-verify`                 | `scip-query status --capabilities`, `scip-query diff-gate --json`                                           |
-| Confirm post-setup health signals before cleanup                                                                   | `scip-health-audit`           | `scip-query health --json --full`, `scip-query diff-gate --json`                                            |
-| Raise the health score as high as reasonably possible with autonomous verified cleanup                             | `scip-health-improve`         | `scip-query health --json --full`, `scip-query cleanup-plan --verify --json`, `scip-query diff-gate --json` |
-| Audit dead code, duplication, unnecessary abstractions, or structural bloat and produce a prioritized cleanup plan | `scip-debloat`                | `scip-query health`                                                                                         |
-| Clean up recent AI-assisted coding rot, copied echoes, incomplete migrations, speculative params, or doc drift     | `scip-ai-cleanup`             | `scip-query recent-duplicates`, `scip-query incomplete-migration`                                           |
-| Reconcile docs/standards that drifted from the code                                                                | `scip-doc-reconcile`          | `scip-query doc-drift <doc>`                                                                                |
-| Review or redesign source folder structure and ownership boundaries                                                | `scip-directory-architecture` | `scip-query locality-candidates --json --full`, `scip-query similar-files --full`                           |
-| Review architecture, hidden policies, weak boundaries beyond folder structure                                      | `scip-maintainability`        | `scip-query bottlenecks`, `scip-query coupling`                                                             |
-| Review React frontend reuse, components, hooks, or TSX/JSX maintainability                                         | `scip-react-maintainability`  | `scip-query react-component-duplicates --full`, `scip-query react-hook-candidates --full`                   |
-| Review Vue frontend reuse, SFCs, templates, or composables                                                         | `scip-vue-maintainability`    | `scip-query vue-component-duplicates --full`, `scip-query vue-composable-candidates --full`                 |
-
-## Tie-break close calls
-
-Use these boundaries before loading a specialist skill:
-
-- `scip-health-audit` confirms, ranks, and reports health signals before code
-  changes. It is the right first step when the user asks "what needs fixing?"
-  or when setup produced a health dossier.
-- `scip-health-improve` is the autonomous campaign. Use it when the user asks
-  to raise/maximize the health score, keep working with minimal interaction, or
-  get the repo as clean as reasonably possible.
-- `scip-hyper-optimization` is the benchmark-led performance campaign. Use it
-  when the user asks to make a command, detector, indexer, workflow, or app path
-  as fast as possible while preserving output.
-- `scip-debloat` is a bloat audit and cleanup plan. Use it when the user wants
-  dead code, duplication, unnecessary abstractions, wrappers, or structural
-  waste found and prioritized, but has not asked for a score-maxing campaign.
-- `scip-ai-cleanup` is for AI-session residue: recent re-implementations of
-  established code, incomplete helper migrations, speculative parameters,
-  stale docs caused by generated changes, and echo code introduced in the
-  current or recent work.
-- `scip-maintainability` is for deeper design pressure: hidden policies,
-  scattered concepts, weak boundaries, accidental variation, and system
-  compression. Use it when the problem is not just "delete waste" but "make the
-  codebase easier to reason about."
-- `scip-directory-architecture` is only for folder ownership and migration
-  questions. Use it when the user asks where code should live, whether
-  boundaries are mature, or how to reorganize source directories.
-
-Invoke skills by name (Skill tool or slash command). If skill invocation is
-unavailable in this harness, read `~/.agents/skills/<name>/SKILL.md` and
-follow it directly.
-
-## Match the post-check to the change
-
-After implementing, run the checks for what the change actually did — every
-row, every time it applies:
-
-| You just...                                           | Run                                                                                                                          |
-| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| Extracted a helper / created an abstraction           | `scip-query incomplete-migration` — lists call sites that still hold the logic inline; migrate them or state why they differ |
-| Wrote a brand-new helper or module                    | `scip-query similar <it>` and `scip-query recent-duplicates` — reuse beats re-implementation; delete the echo                |
-| Added parameters, options, or config flags            | `scip-query unused-params` — speculative "for later" params must go                                                          |
-| Added a forwarding or wrapper layer                   | `scip-query wrapper-candidates` and `scip-query passthrough-candidates` — indirection must earn its keep                     |
-| Added an interface, base class, or type alias         | `scip-query stale-abstractions` — one real consumer is not an abstraction                                                    |
-| Changed a schema, contract, config, or generated file | `scip-query co-change <file>` — update the historical partners or confirm the coupling broke                                 |
-| Changed code that docs describe                       | `scip-query doc-drift` — update the docs that now lie                                                                        |
-| Deleted code                                          | `scip-query cleanup-plan --verify` — take the whole cascade with compiler proof                                              |
-
-Confusable detectors (full guide: docs/DETECTOR_GUIDE.md): `unused-params` is
-parameter-level; `passthrough-candidates` = one **callee** (only forwards);
-`wrapper-candidates` = one **caller** (no reuse); `stale-abstractions` is
-type-level. `recent-duplicates` = similarity + git age (which copy is the
-echo); `incomplete-migration` = the inverse (the new helper is canonical, the
-old inline copies must go).
-
-**Before declaring any change done** — run `scip-query diff-gate --json`. Exit 1
-means findings, each with a remediation. Fix them or knowingly accept them
-with a stated reason; never ignore them silently.
-
-## One-time project setup
-
-If this project has not been bootstrapped yet, run `scip-query setup`. It
-installs bundled skills, checks indexer readiness, refreshes the index, runs
-capability and health checks, writes the health dossier, and seeds agent
-guidance. Use `scip-query setup-agent` only when you specifically need to
-refresh AGENTS.md/CLAUDE.md guidance without the full setup pass.
-Use `scip-query setup-hooks --json` to repair the current repository's
-project-local Codex/Claude Code lifecycle hooks.
-After setup, use `scip-health-audit` to confirm and rank raw health signals, or
-`scip-health-improve` when the user wants the agent to raise the score as high
-as reasonably possible with minimal interaction.
-
-Do not use `scip-query setup-ci` as part of first-run setup. The CI workflow is
-intentionally separate until its validation story is mature.
+Use this skill only to route. A scip-query workflow is a codebase task whose claims should be grounded in the SCIP index: the compiler-derived map of files, symbols, references, calls, dependencies, and consumers.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md) when you need freshness, lookup, postcheck, or subagent rules.
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query status --capabilities` | Show index status for this project | Before routing: confirm the index is fresh. |
+| `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | Default loop: anchor a plan for the routed skill. |
+| `scip-query diff-gate --json` | Gate the current diff: echo candidates, incomplete migrations, missing co-change partners, unedited twin partners (advisory), uncited doc updates, unused params, new dead symbols; exit 1 on blocking findings | Default loop: the loop is complete only when this passes or is explained. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Default Loop
+
+For non-trivial code changes:
+
+1. Invoke `scip-concrete-plan`; the plan starts from `scip-query plan-context <target>` and designs for testability.
+2. Implement the plan in the smallest coherent slice.
+3. Invoke `scip-verify`.
+
+The loop is complete only when `scip-verify` passes or each remaining finding has a specific reason.
+
+## Routes
+
+| Work | Skill | Anchor |
+| --- | --- | --- |
+| Understand a system before answering or editing | `scip-explore` | `system`, `trace`, `call-graph`, `dataflow` |
+| Root-cause a bug or regression | `scip-debug` | `trace`, `dataflow`, `change-surface` |
+| Turn a report into a fix packet | `scip-triage-issue` | `files`, `trace`, `affected` |
+| Create a code flow, dependency, or blast-radius diagram | `scip-diagram` | `call-graph`, `dataflow`, `affected` |
+| Plan a feature, fix, or refactor | `scip-concrete-plan` | `plan-context` |
+| Run a multi-phase program: plan, delegate, verify handoffs, close | `scip-conductor` | `plan-context`, `diff-gate`, `health` |
+| Assess public API, route, config, schema, CLI, or export changes | `scip-api-impact` | `surface`, `affected`, `co-change` |
+| Pick language-specific high-signal commands | `scip-language-playbook` | language row |
+| Benchmark and optimize a command, workflow, or hot path | `scip-hyper-optimization` | `bench`, `plan-context`, profiles |
+| Adopt or repair scip-query setup in a repo | `scip-setup` | `setup`, `doctor`, `capabilities` |
+| Verify any finished change | `scip-verify` | `status`, `diff-impact`, final gate |
+| Audit, rank, or confirm cleanup findings | `scip-cleanup-audit` | `health`, `cleanup-plan`, cleanup detectors |
+| Autonomously fix confirmed cleanup findings | `scip-cleanup-improve` | `health`, `cleanup-plan`, verified batches |
+| Find or resolve same-name twins that have diverged | `scip-twin-drift` | `twin-drift`, `duplicate-bodies`, `refs` |
+| Faked or half-implemented features, checkers that never fail, dead paths behind fallbacks, lying metrics | `scip-integrity-audit` |
+| Audit whether a status claim is derived, hedged, or merely asserted | `scip-claim-audit` | `refs`, `code`, `trace` |
+| Prove whether a parser/AST branch is actually reachable | `scip-probe-reachability` | `outline --signatures`, `code`, scratch probes |
+| Reconcile living docs with code | `scip-doc-reconcile` | `doc-drift` |
+| Review or migrate folder ownership | `scip-directory-architecture` | `locality-candidates`, `similar-files` |
+| Review deeper maintainability and system compression | `scip-maintainability` | `bottlenecks`, `similar-chains`, `change-surface` |
+| Review React reuse and component/hook pressure | `scip-react-maintainability` | React duplicate and pressure commands |
+| Review Vue reuse and SFC/composable pressure | `scip-vue-maintainability` | Vue duplicate and pressure commands |
+| Model a TypeScript system with TLA+ | `scip-tla-model-system` | `plan-context`, `tla verify` |
+
+Routing is complete only when one owning skill is selected or the task is small enough for the default loop alone.
+
+## Tie-Breaks
+
+- "Is this implementation real / does it actually work" → `scip-integrity-audit`; "is this well-organized" → `scip-maintainability`; same-name drifted twins specifically → `scip-twin-drift`.
+- One change → `scip-concrete-plan`; a program of changes with delegation → `scip-conductor`.
+
+- Use `scip-cleanup-audit` for reports, ranking, confirmation, or recent AI-residue triage without edits.
+- Use `scip-cleanup-improve` when the user asks to fix, improve, continue cleaning, or raise health autonomously.
+- Use `scip-maintainability`, `scip-directory-architecture`, or `scip-hyper-optimization` only when the target is architecture, file ownership, or measured speed/cost rather than cleanup.
+- Use `scip-twin-drift` for same-name/near-name consolidation questions (a specific concept copied and drifted); use `scip-cleanup-audit`/`scip-cleanup-improve` for general bloat, echoes, and duplication sweeps that are not centered on one drifted twin family.
+
+## Setup
+
+If a repository has not been bootstrapped, invoke `scip-setup`. Use `scip-query setup-agent` only to refresh agent guidance, `scip-query setup-hooks --json` only to repair project-local hooks, and `scip-query setup-ci` only when the user explicitly asks for CI setup.
+
+<!-- BEGIN GENERATED ROUTER COMMAND PREVIEW -->
+## Command Preview
+
+Top commands per routed skill, generated from each skill's own `commands:` frontmatter.
+
+| Skill | Top commands |
+| --- | --- |
+| `scip-api-impact` | `scip-query surface <module-or-package>`, `scip-query refs <symbol>`, `scip-query affected <symbol> --json` |
+| `scip-claim-audit` | `scip-query files <pattern>`, `scip-query refs <symbol>`, `scip-query code <symbol>` |
+| `scip-cleanup-audit` | `scip-query health --json`, `scip-query cleanup-plan --verify --json`, `scip-query duplicate-bodies --json --full` |
+| `scip-cleanup-improve` | `scip-query health --json`, `scip-query cleanup-plan --verify --json`, `scip-query cleanup-apply --verified --batch <n>` |
+| `scip-concrete-plan` | `scip-query status --capabilities`, `scip-query plan-context <target>`, `scip-query refs <symbol>` |
+| `scip-conductor` | `scip-query plan-context <target>`, `scip-query diff-gate --json`, `scip-query health --json` |
+| `scip-debug` | `scip-query files <feature-or-error-term>`, `scip-query trace <candidate-symbol>`, `scip-query call-graph <entry-symbol>` |
+| `scip-diagram` | `scip-query system <module>`, `scip-query trace <symbol>`, `scip-query call-graph <symbol>` |
+| `scip-directory-architecture` | `scip-query system <scope>`, `scip-query locality-candidates --json --full`, `scip-query similar-files --full --json` |
+| `scip-doc-reconcile` | `scip-query doc-drift --json --full`, `scip-query doc-drift <doc>`, `scip-query outline <subject-file>` |
+| `scip-explore` | `scip-query stats`, `scip-query system <module-or-scope>`, `scip-query trace <entry-symbol>` |
+| `scip-hyper-optimization` | `scip-query bench --json`, `scip-query bench --json --cold-index --include-heavy --timeout-ms 600000`, `scip-query plan-context <entry-symbol-or-file>` |
+| `scip-language-playbook` | `scip-query stats`, `scip-query files <feature-or-module-name>`, `scip-query outline <file>` |
+| `scip-maintainability` | `scip-query stats`, `scip-query system <scope>`, `scip-query surface <scope>` |
+| `scip-probe-reachability` | `scip-query outline <file> --signatures`, `scip-query code <symbol>`, `scip-query trace <symbol>` |
+| `scip-react-maintainability` | `scip-query react-component-duplicates --scope <scope> --full --json`, `scip-query react-hook-candidates --scope <scope> --full --json`, `scip-query react-large-component-pressure --scope <scope> --full --json` |
+| `scip-setup` | `scip-query setup --json`, `scip-query doctor`, `scip-query status --json` |
+| `scip-tla-model-system` | `scip-query tla scaffold <file>`, `scip-query tla verify <spec>`, `scip-query tla instrument <spec>` |
+| `scip-triage-issue` | `scip-query files <issue-term>`, `scip-query trace <entry-or-error-symbol>`, `scip-query code <entry-or-error-symbol>` |
+| `scip-twin-drift` | `scip-query twin-drift --json --full`, `scip-query duplicate-bodies --json --full`, `scip-query code <symbol>` |
+| `scip-verify` | `scip-query doctor`, `scip-query status --capabilities`, `scip-query diff-impact --json` |
+| `scip-vue-maintainability` | `scip-query augment-vue --project <path-to-tsconfig>`, `scip-query vue-component-duplicates --scope <scope> --full --json`, `scip-query vue-composable-candidates --scope <scope> --full --json` |
+<!-- END GENERATED ROUTER COMMAND PREVIEW -->

package/skills/scip-react-maintainability/SKILL.md

@@ -1,119 +1,101 @@
 ---
 name: scip-react-maintainability
-description: React frontend maintainability review using scip-query's React component duplicate, hook candidate, large component pressure, recent-duplicate, incomplete-migration, and diff-gate commands. Use when reviewing React, TSX, JSX, or Next.js codebases; investigating duplicated components or hooks; checking frontend health pressure; or verifying agents reused React code correctly after a refactor.
+description: Review React maintainability with scip-query. Use for React, TSX, JSX, Next.js, duplicated components, hook candidates, large components, frontend health pressure, or verifying reuse after refactors.
+commands:
+  - template: "scip-query react-component-duplicates --scope <scope> --full --json"
+    when: "Bound and scan: duplicated JSX structure candidates."
+  - template: "scip-query react-hook-candidates --scope <scope> --full --json"
+    when: "Bound and scan: shared state/effect/request extraction candidates."
+  - template: "scip-query react-large-component-pressure --scope <scope> --full --json"
+    when: "Bound and scan: components carrying several reasons to change."
+  - template: "scip-query recent-duplicates --scope <scope> --full --json"
+    when: "Bound and scan: recent code re-implementing established components."
+  - template: "scip-query similar <closest-existing-component-or-hook>"
+    when: "Cross-check candidates: existing component or hook to reuse instead."
+  - template: "scip-query health --scope <scope> --json"
+    when: "Bound and scan: frontend health pressure for the scope."
 ---
 
-# SCIP React Maintainability Review
+# scip-react-maintainability
 
-This skill reviews React frontends by treating components, hooks, JSX structure, and behavior lifecycles as first-class maintainability units. It uses `scip-query` evidence to decide where UI structure, state/effect/request behavior, and large components are carrying duplicated concepts or too many reasons to change.
+Use this skill to review React frontends as maintainable systems of components, hooks, JSX structure, and behavior lifecycles.
 
-A React component duplicate candidate is a pair or group of rendered interface structures that repeat the same user-facing arrangement, controls, states, props, or data-presentation shape enough that a shared component may reduce future divergence.
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 
-A React hook candidate is a pair or group of component behaviors that repeat the same state lifecycle, effects, requests, validation, persistence, callback policy, or derived-data rule enough that a shared hook may make the behavior easier to preserve.
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
 
-Large component pressure is a maintainability signal that one React component or file contains several kinds of knowledge that change for different reasons, such as layout structure, state management, data loading, permission policy, and styling.
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query react-component-duplicates --scope <scope> --full --json` | Find heuristic duplicated React component structure candidates from JSX tags, props, events, and bindings | Bound and scan: duplicated JSX structure candidates. |
+| `scip-query react-hook-candidates --scope <scope> --full --json` | Find heuristic React hook extraction candidates from shared state, effects, requests, and handlers | Bound and scan: shared state/effect/request extraction candidates. |
+| `scip-query react-large-component-pressure --scope <scope> --full --json` | Find heuristic large React component pressure candidates from component lines, JSX structure, and hook behavior | Bound and scan: components carrying several reasons to change. |
+| `scip-query recent-duplicates --scope <scope> --full --json` | Directional duplicate candidates: recent code that re-implements established callable, React, or Vue code | Bound and scan: recent code re-implementing established components. |
+| `scip-query similar <closest-existing-component-or-hook>` | Find heuristic function similarity candidates from callee fingerprints | Cross-check candidates: existing component or hook to reuse instead. |
+| `scip-query health --scope <scope> --json` | Composite codebase health report with prioritized action list | Bound and scan: frontend health pressure for the scope. |
 
-React health is a repo-grounded frontend pressure map. It is useful for ranking review attention, but it is not proof that code is bad and not the goal of a refactor.
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
 
-## Quick Start
+## Terms
 
-Refresh the code intelligence before trusting graph facts:
+A React component duplicate candidate is a pair or group of rendered structures that repeat the same user-facing arrangement, controls, states, props, or data-presentation shape enough that a shared component may reduce drift.
 
-```bash
-scip-query status
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
-```
+A React hook candidate is a pair or group of component behaviors that repeat the same state lifecycle, effects, requests, validation, persistence, callback policy, or derived-data rule enough that a shared hook may preserve behavior better.
+
+Large component pressure means one component or file contains several kinds of knowledge that change for different reasons.
+
+## Workflow
+
+### 1. Bound and scan
 
-Run the React review commands uncapped when doing a serious frontend pass. Do not combine `--full` with `--limit`.
+Pick the narrowest React source root, feature area, or changed-file scope that still includes likely reuse partners. Run uncapped commands:
 
 ```bash
-scip-query react-component-duplicates --scope <react-source-scope> --full --json
-scip-query react-hook-candidates --scope <react-source-scope> --full --json
-scip-query react-large-component-pressure --scope <react-source-scope> --full --json
-scip-query recent-duplicates --scope <react-source-scope> --full --json
-scip-query health --scope <react-source-scope> --json
+scip-query react-component-duplicates --scope <scope> --full --json
+scip-query react-hook-candidates --scope <scope> --full --json
+scip-query react-large-component-pressure --scope <scope> --full --json
+scip-query recent-duplicates --scope <scope> --full --json
+scip-query health --scope <scope> --json
 ```
 
-## Workflow
+This step is complete only when command scope, counts, and uncapped/full status are recorded.
+
+### 2. Cross-check candidates
 
-1. Bound the review to a React source root, feature area, or changed files. Prefer the narrowest scope that still includes likely reuse partners.
-2. Run the three React commands: component duplicates, hook candidates, and large component pressure.
-3. Use `recent-duplicates` to catch newly added frontend echoes of established code.
-4. Cross-check the result sets before recommending an extraction:
-   - Component duplicate only: inspect for a shared presentational component or an existing component callers should reuse.
-   - Hook candidate only: inspect for a shared behavior, lifecycle, request pattern, validation rule, persistence rule, or derived-state policy.
-   - Both component and hook candidate: inspect for a feature-level concept that may need both a component boundary and a hook boundary.
-   - Large component only: split by reason to change, not by line count alone.
-5. Open the source files for the top candidates. Similarity is evidence to inspect, not a verdict.
-6. Check existing exports, imports, and call sites before proposing anything new:
+- Component duplicate only: inspect for shared presentational component or existing component reuse.
+- Hook candidate only: inspect for shared behavior, lifecycle, request, validation, persistence, or derived-state policy.
+- Both: inspect for a feature-level concept needing both component and hook boundaries.
+- Large component only: split by reason to change, not by line count.
+
+Use:
 
 ```bash
 scip-query outline <file>
 scip-query deps <file>
 scip-query rdeps <file>
-scip-query similar-files --scope <react-source-scope>
+scip-query similar-files --scope <scope>
 scip-query similar <closest-existing-component-or-hook>
 ```
 
-## Acting on Findings
-
-Prefer reuse before extraction. If an existing component or hook already names the concept, migrate callers to it instead of creating another one.
+This step is complete only when each top candidate is reuse, extract, split, skip, or blocked.
 
-When extracting:
+### 3. Act on findings
 
-- Extract a component when the repeated knowledge is rendered UI structure, props, slots/children, empty/loading/error states, or design-system composition.
-- Extract a hook when the repeated knowledge is state, effects, requests, subscriptions, memoized derivations, callbacks, or persistence policy.
-- Split a large component by reason to change: data loading, permission/policy, layout shell, table/list rendering, form state, and action handling are different reasons.
-- Keep domain-specific variation at the call site when the variation is essential. Do not hide different product rules behind a boolean soup API.
+Prefer reuse before extraction. Extract components for repeated UI structure, states, props, slots/children, or design-system composition. Extract hooks for repeated state, effects, requests, subscriptions, memoized derivations, callbacks, or persistence. Keep domain-specific variation at call sites when essential.
 
-## Post-Change Verification
+This step is complete only when the chosen action reduces future drift without creating boolean-soup APIs or wrapper components with no policy.
 
-After implementing a component reuse, hook extraction, or large-component split, prove both sides of the work: the new abstraction exists and the old inline copies were migrated.
+### 4. Verify
 
-Run the checks that match what changed:
+Run routed postchecks from the shared reference, including React commands, `incomplete-migration`, `recent-duplicates`, `unused-params`, and wrapper/passthrough/stale checks, then invoke `scip-verify`.
 
-```bash
-scip-query diff-impact --json
-scip-query react-component-duplicates --scope <react-source-scope> --full --json
-scip-query react-hook-candidates --scope <react-source-scope> --full --json
-scip-query react-large-component-pressure --scope <react-source-scope> --full --json
-scip-query recent-duplicates --scope <react-source-scope> --full --json
-scip-query incomplete-migration
-scip-query unused-params
-scip-query wrapper-candidates --scope <react-source-scope> --full --json
-scip-query passthrough-candidates --scope <react-source-scope> --full --json
-scip-query stale-abstractions --scope <react-source-scope> --include-low-confidence --full --json
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
-scip-query diff-gate --json
-```
-
-Use the results this way:
-
-- `incomplete-migration`: if a new hook/helper was created and wired somewhere, migrate every unchanged site that still contains the same logic or document why it is not the same behavior.
-- `recent-duplicates`: if the new component/hook is still an echo of established code, delete the echo or reuse the established concept.
-- React duplicate commands: the specific candidate pair you acted on should disappear, weaken materially, or be explicitly accepted as essential variation.
-- `unused-params`: remove speculative props/options introduced "for later."
-- wrapper/pass-through/stale checks: remove local wrapper components, hook aliases, or type abstractions that do not enforce a real policy.
-- `diff-gate`: treat every finding as unfinished work unless there is a written reason to accept it.
+The work is complete only when acted-on candidate pairs disappear, weaken materially, or are explicitly accepted as essential variation.
 
 ## False Positive Checks
 
-- Shared design-system primitives, icons, labels, route names, or test IDs are not enough to justify an extraction.
-- Similar JSX with different domain lifecycles may justify a presentational component but not a hook.
-- Shared hook usage may mean the right concept is already extracted; look for drift around the shared call, not another extraction.
-- A large file creates review pressure, but it is not proof that behavior is duplicated.
-- A local wrapper is justified only when it names a real product concept, enforces a policy, or prevents drift across callers.
-
-## Reporting Shape
+Shared design-system primitives, icons, labels, route names, or test IDs are not enough. Similar JSX with different domain lifecycles may justify a presentational component but not a hook. A large file is review pressure, not proof of duplication.
 
-Report findings as a frontend maintainability register:
+## Report
 
-- Executive read: whether the React code is consolidating or drifting.
-- Command evidence: exact commands, scope, counts, and whether results were uncapped.
-- Candidate groups: files/components, repeated UI structure, repeated behavior, and large-component pressure.
-- Recommended action: reuse existing API, extract component, extract hook, split view, delete wrapper, or no action.
-- Post-change proof: commands rerun, candidate pairs resolved or accepted, migration completeness checked, and `diff-gate` result.
+Report executive read, command evidence, candidate groups, recommended action, post-change proof, and remaining accepted variation.

package/skills/scip-setup/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: scip-setup
+description: Set up or repair scip-query in a repository. Use for bootstrapping, onboarding, refreshing indexes, project-local hooks, agent guidance, capability diagnostics, health dossiers, .scipquery.json, or setup cleanup handoff.
+commands:
+  - template: "scip-query setup --json"
+    when: "Run setup: install skills, refresh the index, report health."
+  - template: "scip-query doctor"
+    when: "Resolve blockers: human diagnostic for config, index, and dependencies."
+  - template: "scip-query status --json"
+    when: "Resolve blockers: machine surface for freshness and config."
+  - template: "scip-query capabilities --matrix"
+    when: "Resolve blockers: which evidence/verification capabilities are available."
+  - template: "scip-query config-validate --json"
+    when: "Resolve blockers: validate .scipquery.json."
+  - template: "scip-query init"
+    when: "Calibrate config: create .scipquery.json only when absent and needed."
+---
+
+# scip-setup
+
+Use this skill to make a repository a reliable scip-query workspace: indexed, diagnosed, documented for agents, and honest about unavailable capabilities.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query setup --json` | Bootstrap this project: install agent skills, refresh the index, verify capabilities, and report health | Run setup: install skills, refresh the index, report health. |
+| `scip-query doctor` | Diagnose config, index freshness, dependency readiness, and project capabilities | Resolve blockers: human diagnostic for config, index, and dependencies. |
+| `scip-query status --json` | Show index status for this project | Resolve blockers: machine surface for freshness and config. |
+| `scip-query capabilities --matrix` | Report which evidence and verification capabilities are available in this project | Resolve blockers: which evidence/verification capabilities are available. |
+| `scip-query config-validate --json` | Validate .scipquery.json, including structured suppressions and declared coupling groups | Resolve blockers: validate .scipquery.json. |
+| `scip-query init` | Create a .scipquery.json config file for this project | Calibrate config: create .scipquery.json only when absent and needed. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Per-Repo Triage (once, after setup)
+
+New repos surface standing findings that are intentional. Encode them once so
+every later gate run is precise:
+
+1. Sweep initial findings (`health --json`, `diff-gate --json`) and, for each accepted one, `suppress <id> --reason <why>` — reasons are required and audited.
+2. Declare files that legitimately change together in `.scipquery.json` `declaredCouplings`.
+3. List dated snapshot docs (benchmarks, validation ledgers, historical plans/reviews) in `docs.snapshotPaths` so doc checks skip them with a labeled exclusion instead of recurring findings.
+4. Seed `coverageContracts` for every hand-maintained enumeration (policy maps, capability tables, registry lists) so enumeration rot fails the gate the day it happens.
+5. Set a hygiene cadence: run `scip-twin-drift` and `scip-claim-audit` after large refactor campaigns or quarterly — the gate only sees diffs; these lenses see accumulated state.
+
+This step is complete only when a clean working tree produces a finding-free `diff-gate` and every suppression carries a reason a reviewer would accept.
+
+## Rules
+
+1. Prefer the single setup command over hand-running its internals.
+2. Do not run `scip-query setup-ci` unless the user explicitly asks for CI setup.
+3. Treat unavailable capabilities as unproven, not clean.
+4. Keep `.scipquery.json` minimal and evidence-backed.
+
+## Workflow
+
+### 1. Confirm the root
+
+```bash
+pwd
+git rev-parse --show-toplevel
+scip-query --version
+```
+
+This step is complete only when the repository root and runnable `scip-query` command are known, or the install/link blocker is reported.
+
+### 2. Run setup
+
+```bash
+scip-query setup --json
+```
+
+Use `scip-query setup --no-hooks --json` when project-local Codex or Claude Code lifecycle hooks should not be written. Use `scip-query setup --git-hook --json` only when the user wants the local pre-commit diff gate.
+
+This step is complete only when setup reports ready, partial, or blocked and names every written, skipped, or blocked artifact.
+
+### 3. Resolve blockers
+
+```bash
+scip-query doctor
+scip-query status --json
+scip-query capabilities --matrix
+scip-query config-validate --json
+```
+
+`doctor` is the human diagnostic surface. `status --json` is the machine surface for freshness and config. Fix missing indexers, stale indexes, invalid config, or unavailable verification only when the fix is safe; otherwise record the exact external action.
+
+This step is complete only when each blocker is fixed, unavailable with reason, or waiting on a named external action.
+
+### 4. Calibrate config only when needed
+
+Run `scip-query init` only when `.scipquery.json` is absent and the project needs config. Add settings only for observed repo facts: explicit languages, indexer projects, entry roots, declared couplings, locality boundaries, or accepted suppressions.
+
+For TypeScript monorepos, prefer `indexer.typescript.projectMode: "workspace"` when multiple project shards are real. Add `indexerConcurrency` only when measured cold-index timing or memory pressure justifies it.
+
+This step is complete only when config validates and every setting has a reason.
+
+### 5. Hand off cleanup
+
+After setup, invoke `scip-cleanup-audit` when the user wants a report or `scip-cleanup-improve` when the user wants autonomous cleanup.
+
+Report:
+
+```markdown
+Setup: ready/partial/blocked
+Capabilities:
+- available:
+- unavailable:
+Health:
+- score:
+- dossier:
+Written or changed:
+- files:
+Next:
+- cleanup audit/improve, CI setup, or external blocker
+```

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "scip-query setup"
+  short_description: "Bootstrap or repair scip-query indexing, diagnostics, hooks, guidance, and health dossiers"
+  default_prompt: "Set up or repair scip-query in this repository, report readiness and blockers, and hand off the next cleanup step."