scip-query 0.10.3 → 0.10.4

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."