scip-query 0.10.2 → 0.10.4

package/skills/scip-query/SKILL.md

@@ -1,7 +1,6 @@
 ---
 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.
-allowed-tools: [Bash, Skill]
 ---
 
 # scip-query Router
@@ -21,26 +20,59 @@ 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. **Run the post-checks that match what you did** (table below) — don't wait
-   to be asked.
-4. **Gate before done** — `scip-query reindex && scip-query diff-gate`; fix
-   findings or state explicitly why each is accepted.
+3. **Verify** — invoke `scip-verify`, then run the post-checks that match what
+   you changed (table below).
+4. **Gate before done** — run `scip-query reindex`, then
+   `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>` |
-| Plan a feature, fix, or refactor | `concrete-plan` | `scip-query plan-context <target>` |
-| Pick high-signal commands for an unfamiliar language | `scip-language-playbook` | — |
-| Verify work you just finished (any implementation, refactor, or extraction) | `scip-verify` | `scip-query reindex && scip-query diff-gate` |
-| Find dead code, duplication, or structural bloat | `scip-debloat` | `scip-query health` |
-| Clean up after AI-assisted coding sessions | `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` |
+| 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`      | —                                                                                                           |
+| 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 reindex`, `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-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
@@ -51,16 +83,16 @@ follow it directly.
 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 |
+| 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);
@@ -69,13 +101,22 @@ 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`. Exit 1
+**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 no agent guidance yet, offer to run
-`scip-query setup-agent` — it seeds the AGENTS.md block (every agent reads
-it) and, with `--git-hook`, installs a pre-commit diff gate that fires no
-matter which agent or human wrote the change.
+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.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Query Router"
+  short_description: "Route codebase work to SCIP skills"
+  default_prompt: "Use $scip-query to choose the right SCIP-backed workflow for this codebase task."

package/skills/scip-query-setup/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: scip-query-setup
-description: Set up or refresh scip-query in a repository so agents can use compiler-resolved code intelligence effectively. Use when adopting scip-query in a repo, fixing stale setup, adding AGENTS.md guidance, checking capability coverage, configuring .scipquery.json, or calibrating locality architectural boundaries.
-allowed-tools: [Bash, Read, Edit, Write, Glob, Skill]
+description: Set up or refresh scip-query in a repository so agents can use compiler-resolved code intelligence effectively. Use when adopting scip-query in a repo, running the robust `scip-query setup` bootstrap, fixing stale setup, adding AGENTS.md guidance, checking capability coverage, generating the health dossier, configuring .scipquery.json, or calibrating locality architectural boundaries.
 ---
 
 # scip-query Setup
@@ -25,38 +24,73 @@ git rev-parse --show-toplevel
 
 ```bash
 scip-query --version
-scip-query status --json
+scip-query doctor
 ```
 
 If the command is missing, install or link it using the repo's package manager, then rerun this step.
 
-3. Create or refresh the index.
+3. Ensure bundled skills are available and project-local lifecycle hooks are configured.
 
 ```bash
-scip-query reindex
-scip-query stats
+scip-query install-skills
+scip-query setup-hooks --json
+```
+
+The setup command also installs skills and configures project-local hooks, but running `install-skills` directly is useful when refreshing a user-level Codex, Claude Code, or shared agents skill root. Use `setup-hooks` when the user wants to repair the current repository's reviewable `.codex/hooks.json` and `.claude/settings.json` files without rerunning the full setup pass.
+
+4. Run the robust local setup pass.
+
+```bash
+scip-query setup --json
 ```
 
-If indexing fails, run `scip-query status --json` and fix the reported missing indexer, language, or config problem before continuing.
+This pass installs bundled skills, configures project-local hooks, checks indexer readiness, attempts configured indexer remediation, refreshes the index, verifies capabilities, smoke-tests representative command families, writes `docs/scip-query/health-dossier.md` and `docs/scip-query/health-dossier.json`, and seeds agent guidance.
 
-4. Seed durable agent guidance.
+If setup reports `blocked`, run:
 
 ```bash
-scip-query setup-agent
+scip-query check-deps
+scip-query capability-matrix --json
 ```
 
-Use `scip-query setup-agent --git-hook` only when the user wants the repository to enforce `diff-gate` before commits.
+Fix the reported missing indexer, toolchain, language, or config problem before continuing. Do not call a missing capability "clean"; record it as unavailable or blocked.
+
+5. Initialize minimal config only when the project needs one.
+
+```bash
+scip-query init
+scip-query config-validate
+```
+
+Keep `.scipquery.json` minimal. Add settings only when they are justified by observed repo facts, reviewed false positives, declared coupling, or explicit suppressions.
+
+6. Refresh the index and inspect project status when setup repairs anything.
+
+```bash
+scip-query reindex
+scip-query status --capabilities
+scip-query capabilities --json
+scip-query stats
+```
 
-5. Check capability coverage.
+If an upstream indexer skipped source files that should still be searchable or visible to agents, run:
 
 ```bash
-scip-query capability-matrix
-scip-query health
+scip-query augment-sources
 ```
 
-Record unsupported or partial capabilities in the setup notes. Do not describe an analyzer as "clean" when the capability matrix says its evidence is unavailable for the language.
+Use `scip-query watch` only for an active local session where repeated source edits need automatic reindexing. It is not part of the default setup proof.
+
+7. Confirm health signals before cleanup.
+
+Invoke `scip-health-audit` after setup when the user wants cleanup, a post-setup follow-through, or a perfect-code pass. The agent must tell the user the health score and list confirmed items before changing application code.
+
+```bash
+scip-query health --json --full
+scip-query diff-gate --json
+```
 
-6. Calibrate project config.
+8. Calibrate project config.
 
 Open or create `.scipquery.json`. Keep config minimal and tied to observed repo facts.
 
@@ -83,7 +117,7 @@ For an unstructured repo, setup runs in discovery mode. Discovery mode means the
 
 Use `locality.architecturalBoundarySegments` only when validation finds a repo-specific mature boundary that is not already in the built-in list. Add folder names, not paths.
 
-7. Validate directory-organization signals when setup touches locality.
+9. Validate directory-organization signals when setup touches locality.
 
 ```bash
 scip-query locality-candidates --json --full
@@ -95,15 +129,28 @@ Validate both suppression and emission. Suppression means a bad generic home was
 
 If the repo has no mature boundaries, the correct setup result is a note, not a config guess: "locality boundaries not configured; repo needs architecture ownership decisions first." A slop codebase is a codebase whose files are arranged by accident, convenience, or recent edits rather than by stable ownership rules. Its defining trait is that directory names do not reliably predict where code should live, so the setup skill must not make `locality-candidates` appear more certain than the repo itself.
 
-8. Finish with the standard gate.
+10. Finish with the standard gate.
 
 ```bash
 scip-query reindex
-scip-query diff-gate
+scip-query diff-gate --json
 ```
 
 Fix findings or state the explicit acceptance reason.
 
+Do not run `scip-query setup-ci` as part of this setup workflow. CI setup is intentionally deferred until that command has a mature validation path.
+
+## Suppressions
+
+Prefer fixing findings. Use suppressions only for intentional design, compatibility shims, framework entry points, or accepted false positives with a specific reason.
+
+```bash
+scip-query suppress <id> --reason "<specific reason>"
+scip-query config-validate
+```
+
+A suppression is a durable acceptance record. It should explain why the code should remain as-is, not merely silence a noisy report.
+
 ## Handoff Notes
 
 When setup changes are complete, record:

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

@@ -0,0 +1,3 @@
+interface:
+  display_name: "scip-query setup"
+  short_description: "Adopt or refresh scip-query indexing, agent guidance, capability checks, and project config"

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

@@ -73,7 +73,7 @@ After implementing a component reuse, hook extraction, or large-component split,
 Run the checks that match what changed:
 
 ```bash
-scip-query diff-impact
+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
@@ -83,7 +83,7 @@ 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 reindex && scip-query diff-gate
+scip-query reindex && scip-query diff-gate --json
 ```
 
 Use the results this way:

package/skills/scip-react-maintainability/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP React Maintainability"
+  short_description: "Review React reuse and component pressure"
+  default_prompt: "Use $scip-react-maintainability to review React reuse, hooks, components, and frontend health pressure."

package/skills/scip-triage-issue/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: scip-triage-issue
+description: Triage bug reports and issues with scip-query evidence. Use when the user shares a GitHub issue, bug report, failing test, support report, TODO, vague defect, or asks to investigate, classify, root-cause, write an issue, or produce a test-first fix plan before implementation.
+---
+
+# SCIP Issue Triage
+
+Use this skill to turn a report into a grounded fix plan. An issue is a described mismatch between expected and observed behavior that needs a tracked decision or code change. Triage is the evidence pass that determines whether the issue is reproducible, where it enters the codebase, what root cause is most likely, and what test should fail before the fix.
+
+## Rules
+
+1. Do not file or implement from the title alone. Extract concrete observed behavior, expected behavior, scope, and reproduction first.
+2. Use scip-query for code evidence: entry points, references, call flow, data flow, blast radius, and similar implementations.
+3. Prefer a failing test plan before a code plan. If no test harness exists, name the smoke command or manual check that will prove the fix.
+4. If the user asks only for triage, stop at the triage packet. If they asked to fix it too, implement after the packet is clear.
+
+## Workflow
+
+### 1. Normalize the report
+
+Record:
+
+- title or short summary;
+- observed behavior;
+- expected behavior;
+- reproduction steps or missing reproduction data;
+- affected surface: CLI command, API route, UI view, job, library export, docs, or config;
+- severity and user impact;
+- known logs, stack traces, screenshots, failing tests, or issue links.
+
+If key facts are missing but the repo can answer them, investigate. Ask the user only when the missing fact is product intent, credentials, private data, or an external system state you cannot inspect.
+
+### 2. Map likely code ownership
+
+```bash
+scip-query status --capabilities
+scip-query reindex
+scip-query files <issue-term>
+scip-query outline <candidate-file>
+scip-query system <module-or-scope>
+scip-query surface <module-or-scope>
+```
+
+Use `scip-query kind-counts --scope <scope>` and `scip-query by-kind function --scope <scope>` when the issue names a broad subsystem and you need an inventory.
+
+### 3. Trace the failing path
+
+```bash
+scip-query trace <entry-or-error-symbol>
+scip-query code <entry-or-error-symbol>
+scip-query call-graph <entry-symbol>
+scip-query dataflow <state-or-input-symbol>
+scip-query slice <state-or-input-symbol>
+```
+
+If a stack trace names a file and line, use `scip-query code '<file>:<start>-<end>'` to read the exact region before following symbols.
+
+### 4. Look for known-good comparisons
+
+```bash
+scip-query similar <suspect-symbol> --json --full
+scip-query convergence <suspect-symbol> <comparison-symbol>
+scip-query similar-files <suspect-file> --json --full
+scip-query co-change <suspect-file> --json --full
+```
+
+Use comparisons to identify a missing guard, validation step, conversion, docs partner, generated artifact, or test fixture.
+
+### 5. Bound impact and test shape
+
+```bash
+scip-query change-surface <suspect-file> --json --full
+scip-query affected <suspect-symbol> --json
+scip-query diff-impact --json
+```
+
+Choose the narrowest failing test that proves the bug. If the issue crosses a public API or generated contract, include `scip-query co-change <file> --json --full` in the plan.
+
+## Triage Packet
+
+Write the packet before filing or fixing:
+
+```markdown
+## Issue
+<one-sentence mismatch>
+
+## Reproduction
+<steps, command, failing test, or missing data>
+
+## Evidence
+- <scip-query command>: <fact>
+
+## Suspected Root Cause
+<earliest code fact that explains the symptom>
+
+## Impact
+- users/surfaces affected
+- blast radius from `scip-query affected` or `change-surface`
+
+## Fix Plan
+1. Add or update failing test/smoke check.
+2. Make the smallest code change.
+3. Run targeted test.
+4. Run `scip-query reindex`.
+5. Run `scip-query diff-gate --json`.
+6. Invoke `scip-verify`.
+
+## Open Questions
+- <product intent or external state only>
+```
+
+If creating a GitHub issue, use the packet as the issue body and include exact file/symbol references. If no root cause is proven, label the result as `needs reproduction` or `needs product decision`, not as ready to implement.

package/skills/scip-triage-issue/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Triage Issue"
+  short_description: "Turn bug reports into evidence-backed fix plans"
+  default_prompt: "Triage this issue with scip-query evidence, identify the root cause, and write a test-first fix plan."