scip-query 0.19.4 → 0.19.5

package/skills/scip-directory-architecture/SKILL.md

@@ -2,26 +2,26 @@
 name: scip-directory-architecture
 description: Review directory architecture with scip-query evidence. Use to evaluate, design, reorganize, or migrate folder structure, ownership boundaries, locality config, messy repos, AI-generated layout, or safe file-move slices.
 commands:
-  - template: "scip-query system <scope>"
-    when: "Inventory evidence: files, symbols, deps in/out for the scope."
-  - template: "scip-query locality-candidates --json --full"
-    when: "Inventory evidence: directory-locality candidates from consumer ownership."
-  - template: "scip-query similar-files --full --json"
-    when: "Inventory evidence: files with overlapping dependency profiles."
-  - template: "scip-query cycles"
-    when: "Inventory evidence: circular dependency chains between files."
-  - template: "scip-query architecture --json"
-    when: "Measure configured boundaries, actual dependency traffic, forbidden edges, reciprocal pairs, and boundary cycles."
-  - template: "scip-query drift --architecture"
-    when: "Review direct drift findings together with boundary coverage and architecture signals."
-  - template: "scip-query co-change --json --full"
-    when: "Inventory evidence: hidden file-level coupling from git history."
-  - template: "scip-query health --write-baseline"
-    when: "Record reviewed existing debt before enabling architecture regression enforcement."
-  - template: "scip-query diff-gate"
-    when: "Verify that the current diff introduces no new declared architecture violation."
-  - template: "scip-query config-validate --json"
-    when: "Implement a slice: validate locality config after a move."
+  - template: 'scip-query system <scope>'
+    when: 'Inventory evidence: files, symbols, deps in/out for the scope.'
+  - template: 'scip-query locality-candidates --json --full'
+    when: 'Inventory evidence: directory-locality candidates from consumer ownership.'
+  - template: 'scip-query similar-files --full --json'
+    when: 'Inventory evidence: files with overlapping dependency profiles.'
+  - template: 'scip-query cycles'
+    when: 'Inventory evidence: circular dependency chains between files.'
+  - template: 'scip-query architecture --json'
+    when: 'Measure configured boundaries, actual dependency traffic, forbidden edges, reciprocal pairs, and boundary cycles.'
+  - template: 'scip-query drift --architecture'
+    when: 'Review direct drift findings together with boundary coverage and architecture signals.'
+  - template: 'scip-query co-change --json --full'
+    when: 'Inventory evidence: hidden file-level coupling from git history.'
+  - template: 'scip-query health --write-baseline'
+    when: 'Record reviewed existing debt before enabling architecture regression enforcement.'
+  - template: 'scip-query diff-gate'
+    when: 'Verify that the current diff introduces no new declared architecture violation.'
+  - template: 'scip-query config-validate --json'
+    when: 'Implement a slice: validate locality config after a move.'
 ---
 
 # scip-directory-architecture
@@ -33,18 +33,18 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 <!-- BEGIN GENERATED SKILL COMMANDS -->
 ## Commands for this skill
 
-| Command | Purpose | When |
-| --- | --- | --- |
-| `scip-query system <scope>` | Full module map: files, symbols, deps in/out | Inventory evidence: files, symbols, deps in/out for the scope. |
-| `scip-query locality-candidates --json --full` | Find directory-locality and ancestry candidates from consumer ownership | Inventory evidence: directory-locality candidates from consumer ownership. |
-| `scip-query similar-files --full --json` | Find heuristic similar-file candidates from dependency profiles | Inventory evidence: files with overlapping dependency profiles. |
-| `scip-query cycles` | Detect circular dependency chains between files | Inventory evidence: circular dependency chains between files. |
-| `scip-query architecture --json` | Evaluate project-owned architectural boundaries and dependency rules | Measure configured boundaries, actual dependency traffic, forbidden edges, reciprocal pairs, and boundary cycles. |
-| `scip-query drift --architecture` | Detect drift candidates: unused imports and declared architecture violations; pass --architecture for boundary context | Review direct drift findings together with boundary coverage and architecture signals. |
-| `scip-query co-change --json --full` | Files that change together in git history without a dependency edge — hidden coupling candidates | Inventory evidence: hidden file-level coupling from git history. |
-| `scip-query health --write-baseline` | Composite codebase health report with prioritized action list | Record reviewed existing debt before enabling architecture regression enforcement. |
-| `scip-query diff-gate` | Gate the current diff: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; exit 1 on blocking findings | Verify that the current diff introduces no new declared architecture violation. |
-| `scip-query config-validate --json` | Validate .scipquery.json, including structured suppressions and declared coupling groups | Implement a slice: validate locality config after a move. |
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query system <scope>` | Full module map: files, symbols, deps in/out | module file paths; exported symbols with line ranges; internal dependencies; reverse dependencies | `complete` | Inventory evidence: files, symbols, deps in/out for the scope. |
+| `scip-query locality-candidates --json --full` | Find directory-locality and ancestry candidates from consumer ownership | symbols, current homes, consumer locality, and suggested homes | `bounded` | Inventory evidence: directory-locality candidates from consumer ownership. |
+| `scip-query similar-files --full --json` | Find heuristic similar-file candidates from dependency profiles | file pairs with similarity scores and shared symbols | `bounded` | Inventory evidence: files with overlapping dependency profiles. |
+| `scip-query cycles` | Detect circular dependency chains between files | dependency-cycle file chains | `bounded` | Inventory evidence: circular dependency chains between files. |
+| `scip-query architecture --json` | Evaluate project-owned architectural boundaries and dependency rules | boundary coverage and dependency-rule violations | `complete` | Measure configured boundaries, actual dependency traffic, forbidden edges, reciprocal pairs, and boundary cycles. |
+| `scip-query drift --architecture` | Detect drift candidates: unused imports and declared architecture violations; pass --architecture for boundary context | drifted symbol families, files, and evidence | `bounded` | Review direct drift findings together with boundary coverage and architecture signals. |
+| `scip-query co-change --json --full` | Files that change together in git history without a dependency edge — hidden coupling candidates | file pairs, co-change counts, confidence, and history context | `bounded` | Inventory evidence: hidden file-level coupling from git history. |
+| `scip-query health --write-baseline` | Composite codebase health report with prioritized action list | health score, findings, priorities, baselines, and coverage notes | `bounded` | Record reviewed existing debt before enabling architecture regression enforcement. |
+| `scip-query diff-gate` | Gate 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` | Verify that the current diff introduces no new declared architecture violation. |
+| `scip-query config-validate --json` | Validate .scipquery.json, including structured suppressions and declared coupling groups | validation diagnostics with config paths | `complete` | Implement a slice: validate locality config after a move. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->
@@ -191,17 +191,29 @@ Use this shape:
 # Directory Architecture Review
 
 ## Scope
+
 ## Current Structure Map
+
 ## Boundary Maturity
+
 ## Descriptive Architecture Model
+
 ## Dependency Rules
+
 ## Forbidden-Edge Ledger
+
 ## Reciprocal and Cycle Review
+
 ## Target Structure
+
 ## Move Ledger
+
 ## Locality Config
+
 ## No-Move Decisions
+
 ## Deferred Decisions
+
 ## Migration Order
 ```
 

package/skills/scip-doc-reconcile/SKILL.md

@@ -2,16 +2,16 @@
 name: scip-doc-reconcile
 description: Reconcile living docs with current code using scip-query doc-drift. Use for stale standards, broken file references, docs that cite moved code, agent guidance, or normative contradictions between documentation and implementation.
 commands:
-  - template: "scip-query doc-drift --json --full"
-    when: "Build the worklist: every stale-doc candidate, ranked."
-  - template: "scip-query doc-drift <doc>"
-    when: "Reconcile one doc: staleness detail for a single target."
-  - template: "scip-query outline <subject-file>"
-    when: "Reconcile one doc: current shape of the code the doc describes."
-  - template: "scip-query trace <symbol>"
-    when: "Reconcile one doc: verify a symbol the doc mentions still exists as described."
-  - template: "scip-query code <symbol>"
-    when: "Reconcile one doc: re-derive a snippet from current source."
+  - template: 'scip-query doc-drift --json --full'
+    when: 'Build the worklist: every stale-doc candidate, ranked.'
+  - template: 'scip-query doc-drift <doc>'
+    when: 'Reconcile one doc: staleness detail for a single target.'
+  - template: 'scip-query outline <subject-file>'
+    when: 'Reconcile one doc: current shape of the code the doc describes.'
+  - template: 'scip-query trace <symbol>'
+    when: 'Reconcile one doc: verify a symbol the doc mentions still exists as described.'
+  - template: 'scip-query code <symbol>'
+    when: 'Reconcile one doc: re-derive a snippet from current source.'
 ---
 
 # scip-doc-reconcile
@@ -23,13 +23,13 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 <!-- BEGIN GENERATED SKILL COMMANDS -->
 ## Commands for this skill
 
-| Command | Purpose | When |
-| --- | --- | --- |
-| `scip-query doc-drift --json --full` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | Build the worklist: every stale-doc candidate, ranked. |
-| `scip-query doc-drift <doc>` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | Reconcile one doc: staleness detail for a single target. |
-| `scip-query outline <subject-file>` | Tree view of symbols in a file, with line ranges | Reconcile one doc: current shape of the code the doc describes. |
-| `scip-query trace <symbol>` | Trace a symbol: definition + all references | Reconcile one doc: verify a symbol the doc mentions still exists as described. |
-| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Reconcile one doc: re-derive a snippet from current source. |
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query doc-drift --json --full` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | document paths, coupled code subjects, and history evidence | `bounded` | Build the worklist: every stale-doc candidate, ranked. |
+| `scip-query doc-drift <doc>` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | document paths, coupled code subjects, and history evidence | `bounded` | Reconcile one doc: staleness detail for a single target. |
+| `scip-query outline <subject-file>` | Tree view of symbols in a file, with line ranges | symbol names, nesting, and line ranges | `complete` | Reconcile one doc: current shape of the code the doc describes. |
+| `scip-query trace <symbol>` | Trace a symbol: definition + all references | definition sites with source and signature; referencing files with line numbers | `bounded` | Reconcile one doc: verify a symbol the doc mentions still exists as described. |
+| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | definition identity, source, and line range | `complete` | Reconcile one doc: re-derive a snippet from current source. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->

package/skills/scip-explore/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: scip-explore
-description: Explore codebases with scip-query evidence. Use to explain how a system, feature, module, call path, dependency graph, data flow, architecture, or change risk works before answering or editing.
+description: Explain how code works, where a feature is implemented, what calls or consumes it, how data flows, or what a change could affect. Uses scip-query to explore an unfamiliar system before answering or editing.
 commands:
-  - template: "scip-query stats"
-    when: "Orient: repo-wide size and shape before naming a scope."
-  - template: "scip-query system <module-or-scope>"
-    when: "Orient: map files, symbols, deps in/out for the scope."
-  - template: "scip-query trace <entry-symbol>"
-    when: "Trace entry points: definition plus every reference."
-  - template: "scip-query call-graph <entry-symbol>"
-    when: "Trace entry points: callers and callees for the path."
-  - template: "scip-query dataflow <symbol-or-variable>"
-    when: "Follow data and state through producers and consumers."
-  - template: "scip-query affected <symbol> --json"
-    when: "Map dependencies and consumers: downstream blast radius."
+  - template: 'scip-query stats'
+    when: 'Orient: repo-wide size and shape before naming a scope.'
+  - template: 'scip-query system <module-or-scope>'
+    when: 'Orient: map files, symbols, deps in/out for the scope.'
+  - template: 'scip-query trace <entry-symbol>'
+    when: 'Trace entry points: definition plus every reference.'
+  - template: 'scip-query call-graph <entry-symbol>'
+    when: 'Trace entry points: callers and callees for the path.'
+  - template: 'scip-query dataflow <symbol-or-variable>'
+    when: 'Follow data and state through producers and consumers.'
+  - template: 'scip-query affected <symbol> --json'
+    when: 'Map dependencies and consumers: downstream blast radius.'
 ---
 
 # scip-explore
@@ -25,14 +25,14 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 <!-- BEGIN GENERATED SKILL COMMANDS -->
 ## Commands for this skill
 
-| Command | Purpose | When |
-| --- | --- | --- |
-| `scip-query stats` | Show index statistics | Orient: repo-wide size and shape before naming a scope. |
-| `scip-query system <module-or-scope>` | Full module map: files, symbols, deps in/out | Orient: map files, symbols, deps in/out for the scope. |
-| `scip-query trace <entry-symbol>` | Trace a symbol: definition + all references | Trace entry points: definition plus every reference. |
-| `scip-query call-graph <entry-symbol>` | Show incoming callers and outgoing callees for a symbol | Trace entry points: callers and callees for the path. |
-| `scip-query dataflow <symbol-or-variable>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | Follow data and state through producers and consumers. |
-| `scip-query affected <symbol> --json` | Transitive closure of symbols that could break if this symbol changes | Map dependencies and consumers: downstream blast radius. |
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query stats` | Show index statistics | document, symbol, definition, reference, size, and build-time totals | `complete` | Orient: repo-wide size and shape before naming a scope. |
+| `scip-query system <module-or-scope>` | Full module map: files, symbols, deps in/out | module file paths; exported symbols with line ranges; internal dependencies; reverse dependencies | `complete` | Orient: map files, symbols, deps in/out for the scope. |
+| `scip-query trace <entry-symbol>` | Trace a symbol: definition + all references | definition sites with source and signature; referencing files with line numbers | `bounded` | Trace entry points: definition plus every reference. |
+| `scip-query call-graph <entry-symbol>` | Show incoming callers and outgoing callees for a symbol | caller and callee symbol identities with files | `bounded` | Trace entry points: callers and callees for the path. |
+| `scip-query dataflow <symbol-or-variable>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | definition sites, usage sites, producer symbols, and consumer symbols | `bounded` | Follow data and state through producers and consumers. |
+| `scip-query affected <symbol> --json` | Transitive closure of symbols that could break if this symbol changes | affected symbol identities, files, and traversal depths | `bounded` | Map dependencies and consumers: downstream blast radius. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->
@@ -40,8 +40,8 @@ Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only
 ## Rules
 
 1. Use a current index before trusting graph facts.
-2. Every behavior, path, consumer, and risk claim cites a scip-query command.
-3. Read source with `scip-query code`; do not describe what a function probably does.
+2. Relationship, consumer, and completeness claims cite scip-query; literal local-source claims may cite a native file read.
+3. Resolve ambiguous symbols before describing behavior. `scip-query code` is useful but not mandatory when an exact native range is already known.
 4. Follow the graph before trusting folder structure.
 5. Start wide, then narrow.
 6. Descriptions need citations; conclusions need discriminators. A conclusion — why something happens, what a unit is for, which intent explains a shape — states one rival explanation and the trace evidence that rules it out.

package/skills/scip-hyper-optimization/SKILL.md

@@ -2,20 +2,20 @@
 name: scip-hyper-optimization
 description: Optimize performance scientifically with scip-query evidence. Use for benchmarking, profiling, speeding up commands, workflows, indexers, detectors, app paths, cold/warm regressions, memory/cost reduction, or comparing current-pipeline tuning with alternative designs.
 commands:
-  - template: "scip-query bench --json"
-    when: "Target and harness: baseline timings for a scip-query command target."
-  - template: "scip-query bench --json --cold-index --include-heavy --timeout-ms 600000"
-    when: "Target and harness: cold-path and heavy-detector timings."
-  - template: "scip-query work-audit <profile> --json"
-    when: "Profile the chain: rank exact repeated computations by measured avoidable time."
-  - template: "scip-query plan-context <entry-symbol-or-file>"
-    when: "Trace behavior: pre-edit context for the profiled entry point."
-  - template: "scip-query call-graph <entry-symbol>"
-    when: "Trace behavior: callers/callees for the pipeline under test."
-  - template: "scip-query complexity <hot-symbol>"
-    when: "Diagnose: branches, cyclomatic estimate, fan-in/out for a hot symbol."
-  - template: "scip-query change-surface <touched-file> --json --full"
-    when: "Verify and report: blast radius of the optimization change."
+  - template: 'scip-query bench --json'
+    when: 'Target and harness: baseline timings for a scip-query command target.'
+  - template: 'scip-query bench --json --cold-index --include-heavy --timeout-ms 600000'
+    when: 'Target and harness: cold-path and heavy-detector timings.'
+  - template: 'scip-query work-audit <profile> --json'
+    when: 'Profile the chain: rank exact repeated computations by measured avoidable time.'
+  - template: 'scip-query plan-context <entry-symbol-or-file>'
+    when: 'Trace behavior: pre-edit context for the profiled entry point.'
+  - template: 'scip-query call-graph <entry-symbol>'
+    when: 'Trace behavior: callers/callees for the pipeline under test.'
+  - template: 'scip-query complexity <hot-symbol>'
+    when: 'Diagnose: branches, cyclomatic estimate, fan-in/out for a hot symbol.'
+  - template: 'scip-query change-surface <touched-file> --json --full'
+    when: 'Verify and report: blast radius of the optimization change.'
 ---
 
 # scip-hyper-optimization
@@ -38,15 +38,15 @@ One sentence to decide: if you can already name the one function you expect to f
 <!-- BEGIN GENERATED SKILL COMMANDS -->
 ## Commands for this skill
 
-| Command | Purpose | When |
-| --- | --- | --- |
-| `scip-query bench --json` | Benchmark indexing and command runtimes for this repository | Target and harness: baseline timings for a scip-query command target. |
-| `scip-query bench --json --cold-index --include-heavy --timeout-ms 600000` | Benchmark indexing and command runtimes for this repository | Target and harness: cold-path and heavy-detector timings. |
-| `scip-query work-audit <profile> --json` | Rank exact repeated computations in a profiling JSONL file by measured avoidable time | Profile the chain: rank exact repeated computations by measured avoidable time. |
-| `scip-query plan-context <entry-symbol-or-file>` | Pre-edit planning context for a symbol, file, or module | Trace behavior: pre-edit context for the profiled entry point. |
-| `scip-query call-graph <entry-symbol>` | Show incoming callers and outgoing callees for a symbol | Trace behavior: callers/callees for the pipeline under test. |
-| `scip-query complexity <hot-symbol>` | Per-symbol complexity: branches, cyclomatic estimate, fan-in/out, callees | Diagnose: branches, cyclomatic estimate, fan-in/out for a hot symbol. |
-| `scip-query change-surface <touched-file> --json --full` | Pre-change briefing: exports, consumers, and blast-radius risk | Verify and report: blast radius of the optimization change. |
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query bench --json` | Benchmark indexing and command runtimes for this repository | timings, command outcomes, environment, and optional profiles | `sampled` | Target and harness: baseline timings for a scip-query command target. |
+| `scip-query bench --json --cold-index --include-heavy --timeout-ms 600000` | Benchmark indexing and command runtimes for this repository | timings, command outcomes, environment, and optional profiles | `sampled` | Target and harness: cold-path and heavy-detector timings. |
+| `scip-query work-audit <profile> --json` | Rank exact repeated computations in a profiling JSONL file by measured avoidable time | ranked repeated-work groups, counts, and avoidable duration | `bounded` | Profile the chain: rank exact repeated computations by measured avoidable time. |
+| `scip-query plan-context <entry-symbol-or-file>` | 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` | Trace behavior: pre-edit context for the profiled entry point. |
+| `scip-query call-graph <entry-symbol>` | Show incoming callers and outgoing callees for a symbol | caller and callee symbol identities with files | `bounded` | Trace behavior: callers/callees for the pipeline under test. |
+| `scip-query complexity <hot-symbol>` | Per-symbol complexity: branches, cyclomatic estimate, fan-in/out, callees | LOC, branch, complexity, callee, fan-in, and fan-out counts | `bounded` | Diagnose: branches, cyclomatic estimate, fan-in/out for a hot symbol. |
+| `scip-query change-surface <touched-file> --json --full` | Pre-change briefing: exports, consumers, and blast-radius risk | defined symbols, external consumer counts, and risk levels | `bounded` | Verify and report: blast radius of the optimization change. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->

package/skills/scip-language-playbook/SKILL.md

@@ -2,16 +2,16 @@
 name: scip-language-playbook
 description: Choose language-specific scip-query commands. Use when entering an unfamiliar TypeScript, Python, Java, Scala, Kotlin, Rust, Go, C, C++, Ruby, C#, Visual Basic, Dart, PHP, Clojure, ClojureScript, or Vue codebase and you need high-signal exploration or de-bloat commands first.
 commands:
-  - template: "scip-query stats"
-    when: "Universal first pass: repo-wide size and shape."
-  - template: "scip-query files <feature-or-module-name>"
-    when: "Universal first pass: locate the files for a feature or module."
-  - template: "scip-query outline <file>"
-    when: "Universal first pass: symbol tree for a candidate file."
-  - template: "scip-query trace <symbol>"
-    when: "Universal first pass: definition plus every reference."
-  - template: "scip-query code <symbol>"
-    when: "Universal first pass: confirm behavior claims with source."
+  - template: 'scip-query stats'
+    when: 'Universal first pass: repo-wide size and shape.'
+  - template: 'scip-query files <feature-or-module-name>'
+    when: 'Universal first pass: locate the files for a feature or module.'
+  - template: 'scip-query outline <file>'
+    when: 'Universal first pass: symbol tree for a candidate file.'
+  - template: 'scip-query trace <symbol>'
+    when: 'Universal first pass: definition plus every reference.'
+  - template: 'scip-query code <symbol>'
+    when: 'Universal first pass: confirm behavior claims with source.'
 ---
 
 # scip-language-playbook
@@ -23,13 +23,13 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 <!-- BEGIN GENERATED SKILL COMMANDS -->
 ## Commands for this skill
 
-| Command | Purpose | When |
-| --- | --- | --- |
-| `scip-query stats` | Show index statistics | Universal first pass: repo-wide size and shape. |
-| `scip-query files <feature-or-module-name>` | Find files matching a pattern | Universal first pass: locate the files for a feature or module. |
-| `scip-query outline <file>` | Tree view of symbols in a file, with line ranges | Universal first pass: symbol tree for a candidate file. |
-| `scip-query trace <symbol>` | Trace a symbol: definition + all references | Universal first pass: definition plus every reference. |
-| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Universal first pass: confirm behavior claims with source. |
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query stats` | Show index statistics | document, symbol, definition, reference, size, and build-time totals | `complete` | Universal first pass: repo-wide size and shape. |
+| `scip-query files <feature-or-module-name>` | Find files matching a pattern | matching file paths | `complete` | Universal first pass: locate the files for a feature or module. |
+| `scip-query outline <file>` | Tree view of symbols in a file, with line ranges | symbol names, nesting, and line ranges | `complete` | Universal first pass: symbol tree for a candidate file. |
+| `scip-query trace <symbol>` | Trace a symbol: definition + all references | definition sites with source and signature; referencing files with line numbers | `bounded` | Universal first pass: definition plus every reference. |
+| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | definition identity, source, and line range | `complete` | Universal first pass: confirm behavior claims with source. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->
@@ -56,23 +56,23 @@ scip-query code <symbol>
 
 ## Language Rows
 
-| Language | Use first | De-bloat set | Fallback note |
-| --- | --- | --- | --- |
-| TypeScript | `system`, `surface`, `call-graph`, `dataflow`, `change-surface` | `health`, `dead`, `similar`, `similar --plan`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `unused-imports`, `redundant-reexports` | Strongest verified surface. Vue script blocks use this path too. |
-| Python | `outline`, `kind-counts --scope`, `system`, `imports`, `imported-by`, `call-graph` | `dead`, `unused-imports`, `drift`, `similar-signatures`, `complexity`, `complexity-hotspots` | Prefer source-backed fallbacks when call/kind metadata is sparse. |
-| Java | `system`, `surface`, `call-graph`, `deps`, `rdeps`, `slice` | `health`, `dead`, `similar-files`, `similar-chains`, `wrapper-candidates`, `stale-abstractions`, `extract-candidates` | Use module/package surfaces to avoid class-only tunnel vision. |
-| Scala | `surface`, `trace`, `call-graph`, `imports`, `imported-by` | `dead`, `similar-files`, `similar-chains`, `extract-candidates`, `stale-abstractions`, `unused-imports` | Confirm behavior with `code`. |
-| Kotlin | `surface`, `trace`, `call-graph`, `imports`, `imported-by` | `dead`, `similar-files`, `similar-chains`, `extract-candidates`, `stale-abstractions`, `unused-imports` | Confirm behavior with `code`. |
-| Rust | `trace`, `call-graph`, `refs`, `methods`, `surface` | `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-signatures`, `redundant-reexports` | Methods and surface are usually high signal. |
-| Go | `surface`, `trace`, `call-graph`, `refs`, `fan-in` | `dead`, `wrapper-candidates`, `passthrough-candidates`, `similar-files`, `similar-signatures`, `complexity` | Use package-level surfaces and confirm exported APIs before cleanup. |
-| C++ | `trace`, `refs`, `methods`, `surface`, `code` | `dead`, `wrapper-candidates`, `similar-files`, `similar-chains`, `extract-candidates`, `unused-imports` | Try `call-graph` after trace/refs/code. |
-| C | `trace`, `call-graph`, `refs`, `outline`, `fan-out` | `dead`, `wrapper-candidates`, `similar-files`, `similar-chains`, `extract-candidates`, `unused-imports` | Skip class/member commands. |
-| Ruby | `trace`, `call-graph`, `refs`, `imports`, `imported-by` | `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-files`, `similar-signatures` | Confirm dynamic-looking paths with source. |
-| C# | `surface`, `call-graph`, `trace`, `methods`, `refs` | `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-files`, `extract-candidates` | Use surfaces and methods together. |
-| Visual Basic | `surface`, `call-graph`, `trace`, `methods`, `refs` | `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-files`, `extract-candidates` | Use surfaces and methods together. |
-| Dart | `surface`, `call-graph`, `trace`, `imports`, `imported-by` | `dead`, `wrapper-candidates`, `stale-abstractions`, `similar-files`, `similar-signatures`, `redundant-reexports` | Confirm exported API shape with `surface`. |
-| PHP | `trace`, `refs`, `methods`, `surface`, `code` | `dead`, `wrapper-candidates`, `stale-abstractions`, `similar-files`, `similar-signatures`, `extract-candidates` | Try `call-graph` after trace/refs/code. |
-| Clojure / ClojureScript | `files`, `outline`, `trace`, `refs`, `call-graph` | `dead`, `similar-files`, `similar-signatures`, `complexity`, `complexity-hotspots` | SCIP indexing comes from `scip-clojure`; no TypeScript-style semantic provider is available. |
+| Language                | Use first                                                                          | De-bloat set                                                                                                                                                 | Fallback note                                                                                |
+| ----------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| TypeScript              | `system`, `surface`, `call-graph`, `dataflow`, `change-surface`                    | `health`, `dead`, `similar`, `similar --plan`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `unused-imports`, `redundant-reexports` | Strongest verified surface. Vue script blocks use this path too.                             |
+| Python                  | `outline`, `kind-counts --scope`, `system`, `imports`, `imported-by`, `call-graph` | `dead`, `unused-imports`, `drift`, `similar-signatures`, `complexity`, `complexity-hotspots`                                                                 | Prefer source-backed fallbacks when call/kind metadata is sparse.                            |
+| Java                    | `system`, `surface`, `call-graph`, `deps`, `rdeps`, `slice`                        | `health`, `dead`, `similar-files`, `similar-chains`, `wrapper-candidates`, `stale-abstractions`, `extract-candidates`                                        | Use module/package surfaces to avoid class-only tunnel vision.                               |
+| Scala                   | `surface`, `trace`, `call-graph`, `imports`, `imported-by`                         | `dead`, `similar-files`, `similar-chains`, `extract-candidates`, `stale-abstractions`, `unused-imports`                                                      | Confirm behavior with `code`.                                                                |
+| Kotlin                  | `surface`, `trace`, `call-graph`, `imports`, `imported-by`                         | `dead`, `similar-files`, `similar-chains`, `extract-candidates`, `stale-abstractions`, `unused-imports`                                                      | Confirm behavior with `code`.                                                                |
+| Rust                    | `trace`, `call-graph`, `refs`, `methods`, `surface`                                | `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-signatures`, `redundant-reexports`                                    | Methods and surface are usually high signal.                                                 |
+| Go                      | `surface`, `trace`, `call-graph`, `refs`, `fan-in`                                 | `dead`, `wrapper-candidates`, `passthrough-candidates`, `similar-files`, `similar-signatures`, `complexity`                                                  | Use package-level surfaces and confirm exported APIs before cleanup.                         |
+| C++                     | `trace`, `refs`, `methods`, `surface`, `code`                                      | `dead`, `wrapper-candidates`, `similar-files`, `similar-chains`, `extract-candidates`, `unused-imports`                                                      | Try `call-graph` after trace/refs/code.                                                      |
+| C                       | `trace`, `call-graph`, `refs`, `outline`, `fan-out`                                | `dead`, `wrapper-candidates`, `similar-files`, `similar-chains`, `extract-candidates`, `unused-imports`                                                      | Skip class/member commands.                                                                  |
+| Ruby                    | `trace`, `call-graph`, `refs`, `imports`, `imported-by`                            | `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-files`, `similar-signatures`                                          | Confirm dynamic-looking paths with source.                                                   |
+| C#                      | `surface`, `call-graph`, `trace`, `methods`, `refs`                                | `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-files`, `extract-candidates`                                          | Use surfaces and methods together.                                                           |
+| Visual Basic            | `surface`, `call-graph`, `trace`, `methods`, `refs`                                | `dead`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `similar-files`, `extract-candidates`                                          | Use surfaces and methods together.                                                           |
+| Dart                    | `surface`, `call-graph`, `trace`, `imports`, `imported-by`                         | `dead`, `wrapper-candidates`, `stale-abstractions`, `similar-files`, `similar-signatures`, `redundant-reexports`                                             | Confirm exported API shape with `surface`.                                                   |
+| PHP                     | `trace`, `refs`, `methods`, `surface`, `code`                                      | `dead`, `wrapper-candidates`, `stale-abstractions`, `similar-files`, `similar-signatures`, `extract-candidates`                                              | Try `call-graph` after trace/refs/code.                                                      |
+| Clojure / ClojureScript | `files`, `outline`, `trace`, `refs`, `call-graph`                                  | `dead`, `similar-files`, `similar-signatures`, `complexity`, `complexity-hotspots`                                                                           | SCIP indexing comes from `scip-clojure`; no TypeScript-style semantic provider is available. |
 
 ## Minimal Workflows
 

package/skills/scip-maintainability/SKILL.md

@@ -2,18 +2,18 @@
 name: scip-maintainability
 description: Review maintainability with scip-query evidence. Use for hidden policies, scattered concepts, accidental variation, weak boundaries, system compression, architecture smells, structural refactors, or maintainability improvements beyond health scores.
 commands:
-  - template: "scip-query stats"
-    when: "Map evidence: repo-wide size before bounding the review."
-  - template: "scip-query system <scope>"
-    when: "Map evidence: files, symbols, deps in/out for the scope."
-  - template: "scip-query surface <scope>"
-    when: "Map evidence: what consumers actually use from the scope."
-  - template: "scip-query change-surface <file>"
-    when: "Map evidence: exports, consumers, and blast-radius risk."
-  - template: "scip-query affected <symbol>"
-    when: "Map evidence: transitive consumers of a candidate symbol."
-  - template: "scip-query drift --patterns --architecture"
-    when: "Map evidence: declared architecture violations plus boundary and pattern signals; treat opt-in pattern hits as leads, not findings."
+  - template: 'scip-query stats'
+    when: 'Map evidence: repo-wide size before bounding the review.'
+  - template: 'scip-query system <scope>'
+    when: 'Map evidence: files, symbols, deps in/out for the scope.'
+  - template: 'scip-query surface <scope>'
+    when: 'Map evidence: what consumers actually use from the scope.'
+  - template: 'scip-query change-surface <file>'
+    when: 'Map evidence: exports, consumers, and blast-radius risk.'
+  - template: 'scip-query affected <symbol>'
+    when: 'Map evidence: transitive consumers of a candidate symbol.'
+  - template: 'scip-query drift --patterns --architecture'
+    when: 'Map evidence: declared architecture violations plus boundary and pattern signals; treat opt-in pattern hits as leads, not findings.'
 ---
 
 # scip-maintainability
@@ -25,14 +25,14 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 <!-- BEGIN GENERATED SKILL COMMANDS -->
 ## Commands for this skill
 
-| Command | Purpose | When |
-| --- | --- | --- |
-| `scip-query stats` | Show index statistics | Map evidence: repo-wide size before bounding the review. |
-| `scip-query system <scope>` | Full module map: files, symbols, deps in/out | Map evidence: files, symbols, deps in/out for the scope. |
-| `scip-query surface <scope>` | What symbols consumers actually use from this module | Map evidence: what consumers actually use from the scope. |
-| `scip-query change-surface <file>` | Pre-change briefing: exports, consumers, and blast-radius risk | Map evidence: exports, consumers, and blast-radius risk. |
-| `scip-query affected <symbol>` | Transitive closure of symbols that could break if this symbol changes | Map evidence: transitive consumers of a candidate symbol. |
-| `scip-query drift --patterns --architecture` | Detect drift candidates: unused imports and declared architecture violations; pass --architecture for boundary context | Map evidence: declared architecture violations plus boundary and pattern signals; treat opt-in pattern hits as leads, not findings. |
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query stats` | Show index statistics | document, symbol, definition, reference, size, and build-time totals | `complete` | Map evidence: repo-wide size before bounding the review. |
+| `scip-query system <scope>` | Full module map: files, symbols, deps in/out | module file paths; exported symbols with line ranges; internal dependencies; reverse dependencies | `complete` | Map evidence: files, symbols, deps in/out for the scope. |
+| `scip-query surface <scope>` | What symbols consumers actually use from this module | consumer paths and consumed symbol identities | `complete` | Map evidence: what consumers actually use from the scope. |
+| `scip-query change-surface <file>` | Pre-change briefing: exports, consumers, and blast-radius risk | defined symbols, external consumer counts, and risk levels | `bounded` | Map evidence: exports, consumers, and blast-radius risk. |
+| `scip-query affected <symbol>` | Transitive closure of symbols that could break if this symbol changes | affected symbol identities, files, and traversal depths | `bounded` | Map evidence: transitive consumers of a candidate symbol. |
+| `scip-query drift --patterns --architecture` | Detect drift candidates: unused imports and declared architecture violations; pass --architecture for boundary context | drifted symbol families, files, and evidence | `bounded` | Map evidence: declared architecture violations plus boundary and pattern signals; treat opt-in pattern hits as leads, not findings. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->
@@ -153,6 +153,6 @@ This step is complete only when each opportunity has evidence, disposition, depe
 
 ### 7. Implement and verify when asked
 
-Implement the smallest named mechanism that matches the real concept. Keep essential variation near the adapter or domain code that knows it. After changes, run focused tests and routed postchecks from the shared reference, then invoke `scip-verify`.
+Implement the smallest named mechanism that matches the real concept. Keep essential variation near the adapter or domain code that knows it. After changes, run focused tests and the routed postchecks in `scip-verify`, then complete that verification skill.
 
 Report the smell addressed, mechanism introduced or removed, what was deliberately not compressed, and verification results.

package/skills/scip-probe-reachability/SKILL.md

@@ -2,11 +2,11 @@
 name: scip-probe-reachability
 description: Prove whether a parser/AST branch is actually reachable by running the real parser on minimal inputs. Use for unreachable or dead node-type/shape branches, wrong node-type strings, tree-sitter grammar mismatches, or any conditional written for an AST or parser output that has never been checked against the real parser.
 commands:
-  - template: "scip-query outline <file> --signatures"
-    when: "Enumerate branches: symbol tree with signatures for the target file."
-  - template: "scip-query code <symbol>"
+  - template: 'scip-query outline <file> --signatures'
+    when: 'Enumerate branches: symbol tree with signatures for the target file.'
+  - template: 'scip-query code <symbol>'
     when: "Enumerate branches: read each branch condition's exact node-type check."
-  - template: "scip-query trace <symbol>"
+  - template: 'scip-query trace <symbol>'
     when: "Enumerate branches: confirm the function's only caller/entry point."
 ---
 
@@ -19,11 +19,11 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 <!-- BEGIN GENERATED SKILL COMMANDS -->
 ## Commands for this skill
 
-| Command | Purpose | When |
-| --- | --- | --- |
-| `scip-query outline <file> --signatures` | Tree view of symbols in a file, with line ranges | Enumerate branches: symbol tree with signatures for the target file. |
-| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Enumerate branches: read each branch condition's exact node-type check. |
-| `scip-query trace <symbol>` | Trace a symbol: definition + all references | Enumerate branches: confirm the function's only caller/entry point. |
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query outline <file> --signatures` | Tree view of symbols in a file, with line ranges | symbol names, nesting, and line ranges | `complete` | Enumerate branches: symbol tree with signatures for the target file. |
+| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | definition identity, source, and line range | `complete` | Enumerate branches: read each branch condition's exact node-type check. |
+| `scip-query trace <symbol>` | Trace a symbol: definition + all references | definition sites with source and signature; referencing files with line numbers | `bounded` | Enumerate branches: confirm the function's only caller/entry point. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->
@@ -86,6 +86,7 @@ Branches:
 | --- | --- | --- | --- |
 
 Findings:
+
 - <branch> — dead branch / wrong node-type string — fix: <direction>
 ```