scip-query 0.10.12 → 0.11.0

package/skills/scip-maintainability/SKILL.md

@@ -1,100 +1,89 @@
 ---
 name: scip-maintainability
-description: Principled maintainability review using scip-query. Finds hidden policies, scattered concepts, accidental variation, weak boundaries, and system-compression opportunities, then proposes or executes structural improvements and verifies post-change wiring without chasing health scores.
+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"
+    when: "Map evidence: layer violations and pattern deviations as probes (--patterns is off by default and near-zero precision; treat hits as leads, not findings)."
 ---
 
-# SCIP Maintainability Review
+# scip-maintainability
 
-You are reviewing a codebase from the standpoint of a senior maintainer. The goal is not to maximize a metric. The goal is to make future changes easier to understand and safer to execute by tying every claim to `scip-query` evidence and by improving the structure that real maintainers must reason about.
+Use this skill to review a codebase as a maintainer who must make future changes safely. Maintainability is the degree to which real code units let a maintainer understand, verify, and change behavior without rediscovering hidden knowledge.
 
-A maintainability review is an architecture review over real code units such as files, symbols, commands, adapters, caches, public exports, tests, and docs. It identifies where one human concept is scattered across several mechanisms, where policy lives in caller folklore, and where accidental variation makes future edits harder than they need to be.
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 
-System compression belongs inside this review. A system compression is a maintainability improvement that replaces several mechanisms performing the same role, policy, lifecycle, or public-surface job with fewer named mechanisms that preserve behavior.
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
 
----
-
-## When to Use This Skill
-
-- "What would a principal engineer notice?"
-- "What is gross here?"
-- "Did this look vibe-coded?"
-- "How should we simplify this architecture?"
-- "Find deeper maintainability problems"
-- "What hidden policies or concepts are scattered?"
-- "Compress this system"
-- "Find the refactor that actually makes this easier to maintain"
-
----
-
-## Hard Rules
-
-1. **Evidence first.** Use `scip-query` to ground claims in files, symbols, references, call graphs, dependencies, surfaces, and blast radius. Check `scip-query status --capabilities`; if freshness is `stale`, `missing`, or `unknown`, run `scip-query reindex` before trusting graph facts.
+| 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` | Detect heuristic drift candidates: unused imports and layer violations by default; pass --patterns for pattern deviations too | Map evidence: layer violations and pattern deviations as probes (--patterns is off by default and near-zero precision; treat hits as leads, not findings). |
 
-2. **Do not chase health scores.** `scip-query health`, detector counts, and LOC estimates are diagnostic signals. They are not the objective. A change is valuable only when it reduces real maintenance burden while preserving behavior.
-
-3. **Name the referents before naming the smell.** A smell is not real until you can point to the concrete files, symbols, tests, or public surfaces that make the future-maintenance risk real.
-
-4. **Preserve essential variation.** Do not compress code merely because it looks similar. Different language grammars, runtime contracts, compatibility boundaries, public APIs, or domain rules may justify different code.
-
-5. **Reject false abstractions.** A new abstraction is justified only when it removes a hidden policy, names a lifecycle, enforces a rule callers were hand-maintaining, or reduces the concept count required for safe change.
-
-6. **Prefer small named mechanisms.** Delete, inline, merge, generate, or enforce before adding broad frameworks.
-
-7. **Treat suppressions as accepted design records.** Prefer fixing findings.
-   Use `scip-query suppress <id> --reason "<specific reason>"` only for
-   intentional design, compatibility shims, framework entry points, or accepted
-   false positives. Run `scip-query config-validate` afterward.
-
----
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
 
-## Core Concepts
+## Terms
 
 A code smell is an observable codebase fact that predicts avoidable future mistakes because the same knowledge must be rediscovered, synchronized, or defended in more than one place.
 
-A concept boundary is the line around code units that exist for one reason to change. A weak boundary mixes unrelated reasons to change, such as parsing syntax, choosing fallback policy, caching data, and rendering output in one module.
+A concept boundary is the line around code units that exist for one reason to change.
 
-A hidden policy is a rule for choosing behavior when several plausible behaviors exist, but the rule is implemented through local branches, repeated comments, naming conventions, or caller folklore instead of a named mechanism.
+A hidden policy is a rule for choosing behavior when several plausible behaviors exist, but the rule lives in local branches, comments, conventions, or caller folklore instead of a named mechanism.
 
-A lifecycle is a repeatable sequence of states or steps that makes a result valid, such as parse -> fallback -> emit, candidate -> evidence -> score -> report, or load -> augment -> write -> invalidate.
+A lifecycle is a repeatable sequence of states or steps that makes a result valid.
 
-Accidental variation is difference in code shape that does not correspond to a difference in behavior, domain facts, runtime constraints, or external contracts.
+Accidental variation is difference in code shape that does not correspond to behavior, domain facts, runtime constraints, or external contracts.
 
-Essential variation is difference that must remain because the real-world units differ, such as different language grammars, indexer capabilities, user-visible APIs, runtime environments, or compatibility boundaries.
+Essential variation is difference that must remain because the real units differ: language grammars, user-visible APIs, runtime environments, or compatibility boundaries.
 
-Concept count is the number of distinct ideas a maintainer must keep active to make a safe change. Lowering concept count is valuable only when the new structure still explains all real variation.
+System compression is replacing several mechanisms that perform the same role, policy, lifecycle, or surface job with fewer named mechanisms that preserve behavior.
 
----
+## Rules
+
+1. Ground claims in files, symbols, references, call graphs, dependencies, surfaces, and blast radius.
+2. Do not chase health scores; detector counts are clues, not objectives.
+3. Name concrete referents before naming the smell.
+4. Preserve essential variation.
+5. Add an abstraction only when it removes hidden policy, names a lifecycle, enforces a rule, or reduces concept count.
+6. Prefer deletion, inlining, merging, generation, or enforcement before broad frameworks.
 
 ## Workflow
 
-### 1. Bound the Review
+### 1. Bound the review
 
-Restate the question in concrete terms:
+Restate the question:
 
 ```text
 What future-maintenance mistakes does this structure invite, and what smaller named mechanisms would prevent them without hiding real variation?
 ```
 
-Identify the scope: whole repo, module, command family, query family, runtime surface, test fixture set, or one feature path.
+Name the scope: repo, module, command family, query family, runtime surface, fixture set, or feature path.
 
-### 2. Refresh and Map Evidence
+This step is complete only when the review question and scope are concrete.
 
-Start from current code intelligence:
+### 2. Map evidence
 
 ```bash
-scip-query status
-scip-query status --capabilities      # Reindex only when freshness is stale, missing, or unknown
 scip-query stats
 scip-query system <scope>
 scip-query surface <scope>
-```
-
-Then map the concrete units:
-
-```bash
 scip-query files <pattern>
 scip-query outline <file>
-scip-query outline <file>
 scip-query deps <file>
 scip-query rdeps <file>
 scip-query trace <symbol>
@@ -103,190 +92,62 @@ scip-query affected <symbol>
 scip-query change-surface <file>
 ```
 
-Use cleanup commands as probes, not verdicts:
+Use cleanup commands as probes: `health`, `similar`, `similar-files`, `similar-chains`, `extract-candidates`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `drift`, and `cycles`.
 
-```bash
-scip-query health --json
-scip-query similar
-scip-query similar-files
-scip-query similar-chains
-scip-query extract-candidates
-scip-query wrapper-candidates
-scip-query passthrough-candidates
-scip-query stale-abstractions --include-low-confidence
-scip-query drift
-scip-query cycles
-```
-
-### 3. Build a Role Inventory
+This step is complete only when concrete units, consumers, tests, fallbacks, adapters, generated artifacts, and compatibility constraints are visible.
 
-For each important cluster, record:
+### 3. Build the role inventory
 
-- concrete files and exported symbols
-- callers and downstream public surfaces
-- tests and fixtures that define behavior
-- fallback paths, caches, registries, adapters, and command handlers
-- generated artifacts or compatibility constraints
-- the role each unit plays in the workflow
+For each cluster, ask:
 
-Ask:
+- What one concept appears in several places?
+- What policy is hidden?
+- What lifecycle is unnamed?
+- Which differences are essential?
+- What must a maintainer know that the local interface does not admit?
+- Would a smaller mechanism remove a reason to change, or only move code?
 
-- What one concept is being implemented in several places?
-- What policy is hidden in branches, comments, argument conventions, or test fixtures?
-- What lifecycle is present but unnamed?
-- Which differences are essential, and which are accidental?
-- What must a new maintainer know that the local interface does not admit?
-- Would a smaller named mechanism remove a reason to change, or only move code around?
+This step is complete only when every candidate smell names its referents and its future-maintenance failure mode.
 
-### 4. Rank Maintainability Pressure
+### 4. Rank pressure
 
 Prefer severe smells in this order:
 
 1. Hidden correctness or evidence policy spread across modules.
-2. Repeated lifecycle or pipeline with no named owner.
-3. Public surface that exposes accidental internals.
-4. Large module with multiple unrelated reasons to change.
+2. Repeated lifecycle or pipeline with no owner.
+3. Public surface exposing accidental internals.
+4. Large module with unrelated reasons to change.
 5. Tests that encode incident history without contract vocabulary.
 6. Adapter families with repeated capability or fallback shapes.
 7. Suppression comments that document architecture decisions instead of exceptions.
-8. Thin wrappers, pass-throughs, and helper layers that do not buy clarity.
+8. Thin wrappers and passthroughs that do not buy clarity.
 
-Reject a target when:
+Reject smells that are aesthetic, unverifiable, or false compression.
 
-- similar code reflects essential variation
-- the new abstraction needs more concepts than it removes
-- a compatibility boundary must stay explicit
-- the smell is only aesthetic
-- the behavior cannot be verified
+This step is complete only when each target is ranked, skipped, or deferred with evidence.
 
-### 5. Choose a Compression Model
+### 5. Choose a model
 
 For substantial changes, compare at least two models:
 
-- conservative: delete or inline local bloat without changing ownership
-- shape-level: introduce one small mechanism that owns a repeated role or lifecycle
-- radical: replace a scattered surface with metadata, generation, or an enforced policy
-
-Evaluate each model by:
-
-- behavior preserved
-- concept count removed
-- blast radius from `affected`, `change-surface`, `deps`, and `rdeps`
-- deletion potential
-- failure mode if the abstraction is false
-- migration path and verification cost
-
-Choose the model that removes a concept or policy duplication, not the model that merely extracts a helper.
+- Conservative: delete or inline local bloat.
+- Shape-level: introduce one small mechanism for a repeated role or lifecycle.
+- Radical: replace a scattered surface with metadata, generation, or enforced policy.
 
-### 6. Produce a Register or Atlas
+Evaluate behavior preserved, concept count removed, blast radius, deletion potential, false-abstraction failure mode, migration path, and verification cost.
 
-For broad review, create or update a register under `docs/plans/` unless the user asks not to edit files:
+This step is complete only when the chosen model removes a concept or policy duplication rather than merely extracting a helper.
 
-```markdown
-# SCIP Maintainability Register
+### 6. Produce a register or atlas
 
-## Executive Read
-## Scope Map
-## Smell Ledger
+For broad review, write a register under `docs/plans/` unless the user asks not to edit files. For implementation, write an atlas before editing.
 
-| Priority | Smell | Evidence | Why it hurts | Better shape | Disposition |
-| --- | --- | --- | --- | --- | --- |
+Use dispositions: `merge`, `delete`, `inline`, `extract`, `generate`, `enforce`, `supersede`, `defer`, `skip`.
 
-## Compression Opportunities
-## Deferred Boundaries
-## Verification Plan
-```
-
-For implementation work, create an atlas before editing:
-
-```markdown
-# <Scope> Maintainability Atlas
-
-## Scope Map
-## Role Inventory
-## Hidden Policies
-## Essential vs Accidental Variation
-## Opportunity Ledger
-## Dependency Order
-## Touch Map
-## Validation Plan
-```
-
-Use dispositions:
-
-- `merge`: combine mechanisms with the same role
-- `delete`: remove proven unused or replaced code
-- `inline`: remove a wrapper, adapter, or single-use abstraction
-- `extract`: isolate a real shared role that multiple consumers need
-- `generate`: derive a surface from metadata instead of maintaining it by hand
-- `enforce`: centralize a policy or invariant so callers cannot drift
-- `supersede`: absorb a local issue into a larger cluster
-- `defer`: keep visible but out of scope because of a verified blocker
-- `skip`: reject because the compression is false or net-negative
-
-### 7. Implement Conservatively
-
-When asked to fix the smells:
-
-- introduce the smallest named mechanism that matches the real concept
-- keep essential variation close to the adapter or domain code that knows it
-- move hidden policies behind interfaces that make the choice visible
-- preserve behavior before broadening scope
-- update registers or docs to record deferred boundaries and why
-
-### 8. Verify the Work
-
-Run focused tests for touched code and repeat the structural probes that motivated the change:
-
-```bash
-scip-query health --json
-scip-query drift
-scip-query stale-abstractions --include-low-confidence
-scip-query wrapper-candidates
-scip-query passthrough-candidates
-scip-query similar-files
-```
-
-Then run the post-change checks that match what the fix actually did:
-
-| Change made | Required post-check |
-| --- | --- |
-| Extracted a helper, hook, composable, component logic, or named abstraction | `scip-query incomplete-migration`; migrate every unchanged site that still contains the extracted logic or document essential variation |
-| Added a new helper, module, component, hook, or composable | `scip-query similar <new-symbol>` when symbol-like, plus `scip-query recent-duplicates --full`; delete echoes of established code |
-| Consolidated duplicated files, command handlers, adapters, or workflows | rerun the detector that motivated the change: `similar-files`, `similar-chains`, `wrapper-candidates`, `passthrough-candidates`, frontend duplicate commands, or `health` |
-| Added parameters, options, config flags, props, or broad option objects | `scip-query unused-params`; remove speculative inputs that no body uses |
-| Added a wrapper, adapter, facade, re-export, or forwarding layer | `scip-query wrapper-candidates`, `scip-query passthrough-candidates`, and `scip-query redundant-reexports` when exports changed |
-| Added an interface, base class, type alias, or abstraction boundary | `scip-query stale-abstractions --include-low-confidence`; prove the abstraction has real consumers and policy |
-| Changed schema, config, generated files, command descriptors, package surface, or docs-backed behavior | `scip-query co-change <file>` and `scip-query doc-drift`; update historical partners and stale docs |
-| Deleted code | `scip-query cleanup-plan --verify`; take the compiler-proven cascade or explain why not |
-
-Always finish implemented maintainability work with:
-
-```bash
-scip-query diff-impact --json
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
-scip-query diff-gate --json
-```
-
-Treat `diff-gate` findings as unfinished work. Fix them or state a concrete acceptance reason; do not silently report success.
-
-Report:
-
-- the named smell addressed
-- the mechanism introduced, deleted, or simplified
-- what was deliberately not compressed
-- verification results, including the post-change checks that matched the edit
-- commit hash, when committed
-
----
+This step is complete only when each opportunity has evidence, disposition, dependency order, touch map, and validation plan.
 
-## Output Style
+### 7. Implement and verify when asked
 
-Be candid, specific, and evidence-grounded:
+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`.
 
-- "This module has three reasons to change."
-- "This helper names a policy that was previously caller folklore."
-- "This is false compression because the two adapters differ by runtime contract."
-- "The health score changed, but that is a side effect, not the reason this was worth doing."
+Report the smell addressed, mechanism introduced or removed, what was deliberately not compressed, and verification results.

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

@@ -0,0 +1,92 @@
+---
+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>"
+    when: "Enumerate branches: read each branch condition's exact node-type check."
+  - template: "scip-query trace <symbol>"
+    when: "Enumerate branches: confirm the function's only caller/entry point."
+---
+
+# scip-probe-reachability
+
+Use this skill for code that branches on a parser or AST node's type or shape (`node.type === '...'`, a grammar-specific tag, a regex over token shape) where nobody has verified the real parser ever produces that type or shape. A branch written from documentation, memory, or a similar grammar in another language can be permanently dead: it looks correct, compiles, and is never exercised by a single test, because the input that should reach it never reaches it under the actual parser.
+
+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. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Rules
+
+1. Never trust a branch condition by reading it; run the real parser on an input constructed to hit it.
+2. Write scratch probe scripts only under the session scratchpad, never inside the repository — they are throwaway evidence, not product code.
+3. Never create a git worktree and never symlink `node_modules` for this skill's probes; import the parser module directly (from `src/` via a TypeScript runner, or from the built package) in a standalone script that needs no repo-root install step.
+4. A branch is a finding whether it is truly unreachable (dead code) or reachable but under a different node-type string than the code checks (a silent misclassification, which is worse than dead code because it fails without raising anything).
+5. Completion requires every node-type/shape branch in the target function to have either a reached probe or a filed finding — partial coverage is not done.
+
+## Workflow
+
+### 1. Enumerate branch conditions
+
+```bash
+scip-query outline <target-file> --signatures
+scip-query code <target-function>
+```
+
+List every conditional that tests a node's `type`, tag name, or shape (an `if`/`else if` chain over `node.type === '...'`, a `switch` on a grammar tag, or a regex matched against node text standing in for a type check). Record the exact string or pattern each branch expects.
+
+This step is complete only when every node-type/shape branch in the target function is listed with its file:line and the exact condition text.
+
+### 2. Construct a minimal input per branch
+
+For each branch, write the smallest source snippet in the target language that should, by the language's grammar, produce a node of that type or shape at that point in the tree. Prefer one snippet per branch; note when a single snippet is expected to exercise more than one branch (siblings in a walk).
+
+This step is complete only when every branch has a candidate input snippet.
+
+### 3. Run the real parser
+
+Write one scratch script under the session scratchpad (never in the repo) that imports the actual parser module used by the target code — not a reimplementation, not a mental model of the grammar — and, for each candidate snippet:
+
+1. Parses it.
+2. Walks the resulting tree and collects every node type actually produced.
+3. Reports whether the branch's expected type/shape appears anywhere in that set.
+
+Run the script (for example `npx vite-node <scratch-script>` from the repo root, or a plain `node` script importing the built package) and record reached/unreached per branch.
+
+This step is complete only when every branch from step 1 has a recorded reached/unreached result from an actual parser run, not an inference.
+
+### 4. File findings for unreached branches
+
+For each unreached branch, determine and record which of these it is:
+
+- **Dead branch**: the grammar never produces this node type/shape anywhere reachable from valid source in this language; the branch is unreachable code. Fix: delete it, or replace it with the branch that actually covers the intended case (found by inspecting the node types the parser did produce for the candidate input).
+- **Wrong node-type string**: the intended case is real and common, but the branch checks the wrong string (a rename in the grammar, a typo, or a mismatch borrowed from a different language/version). Fix: correct the string to what step 3 actually observed.
+
+This step is complete only when every unreached branch has one of these two labels and a fix direction.
+
+### 5. Report
+
+```markdown
+Target: <file:function>
+
+Branches:
+| Branch condition | Candidate input | Reached? | Finding |
+| --- | --- | --- | --- |
+
+Findings:
+- <branch> — dead branch / wrong node-type string — fix: <direction>
+```
+
+Completion requires every branch from step 1 to appear in the table with a reached/unreached result.

package/skills/scip-probe-reachability/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Probe Reachability"
+  short_description: "Prove parser/AST branches are reachable by running the real parser"
+  default_prompt: "Enumerate the node-type/shape branches in the target parser or AST-consuming function, construct a minimal input per branch, run the real parser on each in a scratch script, and file findings for every unreached branch."