scip-query 0.14.0 → 0.16.0

package/docs/AGENT_GUIDE.md

@@ -14,17 +14,39 @@ For analyzer implementation work, follow [Regex Policy](REGEX_POLICY.md): regex
 ### Steps
 
 1. **Run setup**
+
    ```bash
    scip-query setup --json
    ```
-   Returns: detected languages, indexer readiness, remediation attempts, index result, capability summary, project-local hook install state, smoke tests, health score, issue list, health dossier paths, and setup verdict. Use `scip-query setup --no-hooks --json` when the repo should not write Codex or Claude Code lifecycle hooks.
+
+   Returns: detected languages, automatic-indexing config and live service
+   state, Rust semantic transport/fallback state, indexer readiness,
+   remediation attempts, index result, capability summary, project-local hook
+   install state, smoke tests, health score, issue list, health dossier paths,
+   and setup verdict. A project with no watch decision is enabled; an existing
+   explicit `watch.enabled: false` is preserved. Use `scip-query setup --guided`
+   for a recommended automatic-indexing choice, or
+   `scip-query setup --no-hooks --json` when the repo should not write Codex or
+   Claude Code lifecycle hooks.
+
+   Setup reports three change scopes. Repository records are shared project
+   facts and history that must survive clones, so commit `.scipquery.json`,
+   managed AGENTS/CLAUDE guidance, health dossiers,
+   `.scipquery/suppressions/*.json`, and `.scipquery/ledger/` when setup or a
+   gate run changes them. Checkout preferences configure only one clone, so do
+   not commit `.codex/hooks.json` or `.claude/settings.local.json`; setup keeps
+   them out of Git through `.git/info/exclude`. User-environment changes install
+   skills or indexers for the current machine. Use `setup --guided` to answer
+   each repository, checkout, or user-scope question separately.
 
 2. **Resolve blockers**
+
    ```bash
    scip-query doctor
    scip-query status --json
    scip-query capabilities --matrix
    ```
+
    `doctor` is the human diagnostic. `status --json` is the machine-readable freshness/config surface. `check-deps` and `capability-matrix` remain compatibility aliases, but new workflows should prefer `doctor`, `status`, and `capabilities --matrix`.
 
 3. **Start health follow-through**
@@ -50,33 +72,43 @@ For analyzer implementation work, follow [Regex Policy](REGEX_POLICY.md): regex
 ### Steps
 
 1. **Map the module**
+
    ```bash
    scip-query system <module-path>
    ```
+
    Returns: all files in the module, all exported symbols with line ranges, all inbound and outbound dependencies. This is your starting map.
 
 2. **Understand the public contract**
+
    ```bash
    scip-query surface <module-path>
    ```
+
    Returns: which symbols external consumers actually reference. This is the true public API — not what's exported, but what's used. Any change to these symbols is a breaking change.
 
 3. **Trace specific symbols**
+
    ```bash
    scip-query trace <symbol-name>
    ```
+
    Returns: where the symbol is defined (file + line range + signature) and every file that references it. Use this for any symbol you need to understand deeply.
 
 4. **Map the call graph**
+
    ```bash
    scip-query call-graph <function-name>
    ```
+
    Returns: what calls this function (incoming) and what this function calls (outgoing). Gives you the function's role in the execution flow.
 
 5. **Check blast radius**
+
    ```bash
    scip-query affected <symbol-name>
    ```
+
    Returns: the full transitive closure of symbols that could break if this symbol changes. Depth 1 = direct consumers. Depth 2 = consumers of consumers. Shows the complete ripple effect.
 
 6. **Pre-change briefing**
@@ -102,38 +134,48 @@ For analyzer implementation work, follow [Regex Policy](REGEX_POLICY.md): regex
 ### Steps
 
 1. **Map the target area**
+
    ```bash
    scip-query system <module-path>
    scip-query outline <each-file-you-will-modify>
    ```
+
    Get the structural outline with line ranges for every file in scope. Add `--signatures` only when type details are useful.
 
 2. **Identify the public contract you must preserve**
+
    ```bash
    scip-query surface <module-path>
    ```
+
    Any symbol that appears here must maintain backward compatibility or all consumers must be updated.
 
 3. **Map every symbol you plan to change**
+
    ```bash
    scip-query refs <symbol>        # who uses it
    scip-query affected <symbol>    # transitive blast radius
    scip-query fan-in <symbol>      # quantified consumer count
    ```
+
    For each symbol you'll modify: know exactly who consumes it and how many layers deep the impact goes.
 
 4. **Check blast radius before editing**
+
    ```bash
    scip-query change-surface <file>
    scip-query diff-impact --json
    ```
+
    Identify which symbols in your change set have many external consumers and which downstream files will be affected.
 
 5. **Find reusable code**
+
    ```bash
    scip-query similar <symbol-you-plan-to-write>
    scip-query deps <file>
    ```
+
    Before writing new code, check if something similar already exists. `similar` finds functions with overlapping callee patterns. `deps` shows what the file already imports that you can reuse.
 
 6. **After making changes, verify impact**
@@ -181,68 +223,90 @@ For analyzer implementation work, follow [Regex Policy](REGEX_POLICY.md): regex
 Numeric thresholds below are recommended starting points for review sessions; command defaults may differ.
 
 1. **Get the full health report**
+
    ```bash
    scip-query health
    ```
+
    This runs every analysis and produces a prioritized action list. Start here. The actions are sorted by impact/effort ratio — do the top ones first.
 
 2. **Review dead-code candidates**
+
    ```bash
    scip-query dead --min-loc 10 --skip-barrels
    ```
-   These symbols have zero cross-file references. Treat them as deletion candidates and confirm with `cleanup-plan --verify` before deleting. `--skip-barrels` ignores references from inactive barrel files, which helps surface exports kept alive only by unused re-export layers without hiding live package entry surfaces.
+
+   `dead-code` rows have no repository consumer after test references, declared package exports, framework entrypoints, and language contracts are considered. `file-internal` rows have same-file use but no cross-file consumer and are contextual, not deletion claims. Confirm deletion candidates with `cleanup-plan --verify`. `--skip-barrels` ignores references from inactive barrel files without hiding live package entry surfaces.
 
 3. **Delete isolated symbols**
+
    ```bash
    scip-query isolated --min-loc 5
    ```
+
    Stricter than `dead` — these symbols have zero references anywhere, including in their own file. Completely disconnected from the codebase.
 
 4. **Break circular dependencies**
+
    ```bash
    scip-query cycles
    ```
+
    If any exist, they need structural fixes: dependency inversion, module splitting, or interface extraction.
 
 5. **Consolidate similar functions**
+
    ```bash
    scip-query similar --min-similarity 0.5
    ```
+
    Pairs of functions with overlapping callee sets. For each pair:
+
    ```bash
    scip-query convergence <symbol1> <symbol2>
    ```
+
    Shows what the consolidated version would look like: shared callees = common body, unique callees = parameterization points.
 
 6. **Extract large functions**
+
    ```bash
    scip-query extract-candidates --min-loc 20
    ```
+
    Functions with isolated callee clusters — natural "Extract Method" seams.
 
 7. **Remove unnecessary indirection**
+
    ```bash
    scip-query wrapper-candidates
    scip-query passthrough-candidates
    ```
+
    Wrappers: single-consumer symbols that can be inlined. Passthroughs: functions that just forward to one callee.
 
 8. **Prune premature abstractions**
+
    ```bash
    scip-query stale-abstractions
    ```
+
    Types and interfaces with 0-1 consumers. An interface with one implementation isn't an abstraction.
 
 9. **Fix pattern drift**
+
    ```bash
    scip-query drift --patterns
    ```
+
    Files that deviate from their directory's typical dependency pattern. Bring them into line with their neighbors. `--patterns` is opt-in (off by default since 21.2 calibration found this channel low-precision at scale) — treat hits as leads to confirm, not findings.
 
 10. **Remove redundant re-exports**
+
     ```bash
     scip-query redundant-reexports
     ```
+
     Barrel file entries that nobody imports through. Clean up the barrel.
 
 11. **Find same-shape functions**
@@ -253,16 +317,16 @@ Numeric thresholds below are recommended starting points for review sessions; co
 
 ### Priority order
 
-| Priority | What | Why |
-|---|---|---|
-| 1 | Dead code | High-confidence deletion candidates; verify before deleting |
-| 2 | Isolated symbols | Zero indexed consumers; verify before deleting |
-| 3 | Circular deps | Structural fix, prevents future problems |
-| 4 | Similar functions | Reduces duplication, use `convergence` for prescription |
-| 5 | Extraction candidates | Reduces function complexity |
-| 6 | Wrappers / passthroughs | Removes unnecessary indirection |
-| 7 | Stale abstractions | Removes premature over-engineering |
-| 8 | Pattern drift | Consistency improvement |
+| Priority | What                    | Why                                                         |
+| -------- | ----------------------- | ----------------------------------------------------------- |
+| 1        | Dead code               | High-confidence deletion candidates; verify before deleting |
+| 2        | Isolated symbols        | Zero indexed consumers; verify before deleting              |
+| 3        | Circular deps           | Structural fix, prevents future problems                    |
+| 4        | Similar functions       | Reduces duplication, use `convergence` for prescription     |
+| 5        | Extraction candidates   | Reduces function complexity                                 |
+| 6        | Wrappers / passthroughs | Removes unnecessary indirection                             |
+| 7        | Stale abstractions      | Removes premature over-engineering                          |
+| 8        | Pattern drift           | Consistency improvement                                     |
 
 ---
 
@@ -273,27 +337,34 @@ Numeric thresholds below are recommended starting points for review sessions; co
 ### Steps
 
 1. **Overall health**
+
    ```bash
    scip-query health
    scip-query health --json    # for programmatic use
    ```
 
 2. **Complexity risks**
+
    ```bash
    scip-query complexity-hotspots -n 20
    ```
+
    Symbols with the highest composite score (LOC x fan-in x fan-out). These are the most likely to contain bugs and the hardest to modify.
 
 3. **Coupling risks**
+
    ```bash
    scip-query bottlenecks -n 20
    ```
+
    Symbols with both high fan-in (many consumers) AND high fan-out (many dependencies). Changes to these are risky in both directions.
 
 4. **Architecture depth**
+
    ```bash
    scip-query deep-chains --min-depth 5
    ```
+
    Long transitive dependency chains. If chains are deeper than 6-7, the architecture may need flattening.
 
 5. **Structural drift**
@@ -335,15 +406,19 @@ Numeric thresholds below are recommended starting points for review sessions; co
 ### Steps
 
 1. **Compute diff impact**
+
    ```bash
    scip-query diff-impact --json
    ```
+
    Shows: changed files, changed symbols with fan-in counts, and affected consumer files.
 
 2. **Check transitive impact for critical symbols**
+
    ```bash
    scip-query affected <changed-symbol>
    ```
+
    For any high fan-in symbol that changed, check the full transitive blast wave.
 
 3. **Re-check structural drift around the changed area**
@@ -357,28 +432,29 @@ Numeric thresholds below are recommended starting points for review sessions; co
 
 ## Quick Reference
 
-| I want to... | Run |
-|---|---|
-| Understand a module | `system <module>` |
-| See what consumers actually use | `surface <module>` |
-| Find all references to a symbol | `refs <symbol>` or `trace <symbol>` |
-| See what a function calls and who calls it | `call-graph <symbol>` |
-| Check blast radius of a change | `affected <symbol>` |
-| Get a pre-change briefing | `change-surface <file>` |
-| See impact of my git changes | `diff-impact --json` |
-| Find dead code to delete | `dead --min-loc 10 --skip-barrels` |
-| Find duplicate functions | `similar --min-similarity 0.5` |
-| Find same-shape functions | `similar-signatures --min-loc 5` |
-| Get a refactoring prescription | `convergence <sym1> <sym2>` |
-| Find redundant barrel re-exports | `redundant-reexports` |
-| Find extraction opportunities | `extract-candidates --min-loc 20` |
-| Find unnecessary wrappers | `wrapper-candidates` |
-| Find single-implementation types | `stale-abstractions` |
-| Find pattern outliers | `drift` |
-| Get overall codebase health | `health` |
-| Find riskiest symbols | `complexity-hotspots` |
-| Find coupling pressure points | `bottlenecks` |
-| Find circular dependencies | `cycles` |
+| I want to...                               | Run                                 |
+| ------------------------------------------ | ----------------------------------- |
+| Understand a module                        | `system <module>`                   |
+| See what consumers actually use            | `surface <module>`                  |
+| Find all references to a symbol            | `refs <symbol>` or `trace <symbol>` |
+| See what a function calls and who calls it | `call-graph <symbol>`               |
+| Check blast radius of a change             | `affected <symbol>`                 |
+| Get a pre-change briefing                  | `change-surface <file>`             |
+| See impact of my git changes               | `diff-impact --json`                |
+| Find dead code to delete                   | `dead --min-loc 10 --skip-barrels`  |
+| Find duplicate functions                   | `similar --min-similarity 0.5`      |
+| Find same-shape functions                  | `similar-signatures --min-loc 5`    |
+| Get a refactoring prescription             | `convergence <sym1> <sym2>`         |
+| Find redundant barrel re-exports           | `redundant-reexports`               |
+| Find extraction opportunities              | `extract-candidates --min-loc 20`   |
+| Find unnecessary wrappers                  | `wrapper-candidates`                |
+| Find single-implementation types           | `stale-abstractions`                |
+| Find pattern outliers                      | `drift`                             |
+| Get overall codebase health                | `health`                            |
+| Find riskiest symbols                      | `complexity-hotspots`               |
+| Find coupling pressure points              | `bottlenecks`                       |
+| Find circular dependencies                 | `cycles`                            |
+
 ---
 
 ## Tips for AI Agents

package/docs/AI_FAILURE_MODES.md

@@ -253,9 +253,10 @@ The detectors only help if they run. Three layers, in increasing strength:
 **1. Skills and lifecycle hooks (routing).** Installing scip-query symlinks the
 bundled skills into `~/.agents/skills/`, `~/.claude/skills/`, and
 `~/.codex/skills/` — they update automatically with the package. Project setup
-writes reviewable repo-local hooks to `.codex/hooks.json` and
-`.claude/settings.local.json` by default; `setup-hooks --shared` opts into the
-tracked `.claude/settings.json`. Set `SCIP_QUERY_SKIP_HOOK_INSTALL=1` or run
+writes reviewable checkout-local hooks to `.codex/hooks.json` and
+`.claude/settings.local.json` and excludes both through `.git/info/exclude`.
+The deprecated `setup-hooks --shared` flag remains parse-compatible but no
+longer writes tracked settings. Set `SCIP_QUERY_SKIP_HOOK_INSTALL=1` or run
 `scip-query setup --no-hooks` to skip lifecycle hook setup. The hooks add
 scip-query context at session start, route prompts toward the right specialist,
 and run a safe Stop hook wrapper around the diff gate only for that repository.
@@ -276,6 +277,10 @@ commands, writes `docs/scip-query/health-dossier.md` and `.json`, reports the
 health score and items needing attention, and seeds a managed block in
 `AGENTS.md` plus a `CLAUDE.md` import shim.
 
+The generated guidance distinguishes shared repository records from local
+preferences. Commit suppression files and `.scipquery/ledger/` outcome events
+with the change that produced them. Never commit the checkout hook files.
+
 After setup, use `scip-cleanup-audit` to confirm raw signals and
 `scip-cleanup-improve` when the user wants the agent to fix the worst confirmed
 items until the health score is as high as reasonably possible.

package/docs/COMMAND_REFERENCE.md

@@ -45,7 +45,7 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 
 | Command | Description | Options |
 |---|---|---|
-| `dead [scope]` | Find dead code and file-internal symbols (no cross-file consumers) | `--min-loc <n>`<br>`--include-tests`<br>`--skip-barrels`<br>`--include-members`<br>`--only-dead`<br>`--only-internal`<br>`--full`<br>`--json` |
+| `dead [scope]` | Find repository-dead code, file-internal symbols, and implicit-usage signals | `--min-loc <n>`<br>`--include-tests`<br>`--skip-barrels`<br>`--include-members`<br>`--only-dead`<br>`--only-internal`<br>`--full`<br>`--json` |
 | `unused-imports <file>` | Find imports not referenced in the same file | `--full`<br>`--json` |
 | `isolated` | Find completely orphaned symbols (no references at all) | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--full`<br>`--json` |
 | `similar [symbol] [other]` | Find heuristic function similarity candidates from callee fingerprints | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-callees <n>`<br>`--cross-file-only`<br>`--plan`<br>`--full`<br>`--json` |
@@ -84,12 +84,12 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 | Command | Description | Options |
 |---|---|---|
 | `hotspots` | Most-referenced symbols in the codebase (choke points) | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
-| `fan-in [symbol]` | How many files reference a symbol (or top fan-in across codebase) | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
+| `fan-in [symbol]` | Count files referencing an exact symbol; top JSON rows include exact symbol identity | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
 | `fan-out [file]` | How many external symbols a file uses (or top fan-out across codebase) | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
 | `coupling [file1] [file2]` | Coupling between two files, or top coupled pairs in codebase | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json` |
 | `cycles` | Detect circular dependency chains between files | `-s, --scope <path>`<br>`--max-depth <n>`<br>`--json` |
 | `bottlenecks` | Find coupling hubs: high fan-in AND high fan-out | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-fan-in <n>`<br>`--min-fan-out <n>`<br>`--full`<br>`--json` |
-| `deep-chains` | Find the longest transitive dependency chains | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-depth <n>`<br>`--full`<br>`--json` |
+| `deep-chains` | Find the longest condensed dependency-component chains | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-depth <n>`<br>`--full`<br>`--json` |
 | `call-graph <symbol>` | Show incoming callers and outgoing callees for a symbol | `--full`<br>`--json` |
 
 ### Impact
@@ -128,6 +128,7 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 | Command | Description | Options |
 |---|---|---|
 | `bench` | Benchmark indexing and command runtimes for this repository | `--json`<br>`--cold-index`<br>`--include-heavy`<br>`--command <cmd>`<br>`--timeout-ms <n>`<br>`--progress`<br>`--profile`<br>`--profile-out <path>` |
+| `work-audit <profile>` | Rank exact repeated computations in a profiling JSONL file by measured avoidable time | `--top <n>`<br>`--json` |
 | `install-skills` | Install skills (_shared, scip-query, scip-setup, scip-calibrate, scip-cleanup-audit, scip-cleanup-improve, scip-integrity-audit, scip-twin-drift, scip-claim-audit, scip-probe-reachability, scip-hyper-optimization, scip-api-impact, scip-concrete-plan, scip-conductor, scip-debug, scip-explore, scip-triage-issue, scip-diagram, scip-doc-reconcile, scip-directory-architecture, scip-maintainability, scip-react-maintainability, scip-vue-maintainability, scip-verify, scip-language-playbook, scip-tla-model-system) into Claude Code, Codex, and shared agent roots | - |
 | `setup-hooks` | Install or refresh project-local Codex and Claude Code lifecycle hooks | `--shared`<br>`--remove`<br>`--force`<br>`--json` |
 | `check-deps` | Check whether scip-query and the detected language indexers are actually runnable | - |
@@ -135,13 +136,14 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 | `capability-matrix` | Deprecated alias for capabilities --matrix | `--json` |
 | `init` | Create a .scipquery.json config file for this project | - |
 | `config-validate` | Validate .scipquery.json, including structured suppressions and declared coupling groups | `--json` |
-| `suppress <id>` | Record an accepted finding in .scipquery.json with a required reason | `--reason <text>`<br>`--check <check>`<br>`--file <path>`<br>`--expires-at <iso>`<br>`--json` |
+| `suppress <id>` | Record an accepted finding as a file under .scipquery/suppressions/ with a required reason | `--reason <text>`<br>`--check <check>`<br>`--file <path>`<br>`--expires-at <iso>`<br>`--json` |
+| `effectiveness` | Per-check effectiveness from the committed outcome ledger: caught, same-HEAD verified fixes, suppressed, unverified disappearances, and precision | `--since <window>`<br>`--check <check>`<br>`--json` |
 | `doctor` | Diagnose config, index freshness, dependency readiness, and project capabilities | `--json` |
-| `setup` | Bootstrap this project: install agent skills, refresh the index, verify capabilities, and report health | `--git-hook`<br>`--no-hooks`<br>`--dossier-dir <path>`<br>`--json` |
+| `setup` | Bootstrap this project: enable automatic indexing, install agent skills, refresh the index, verify capabilities, and report health | `--guided`<br>`--yes`<br>`--git-hook`<br>`--no-hooks`<br>`--no-skills`<br>`--no-parsers`<br>`--no-health`<br>`--dossier-dir <path>`<br>`--json` |
 | `setup-agent` | Seed agent guidance for this project: AGENTS.md/CLAUDE.md block pointing agents at the scip-query skills and diff gate, plus an optional git pre-commit backstop | `--git-hook` |
 | `setup-ci` | Write a GitHub Actions workflow that runs scip-query reindex and diff-gate on pull requests | `--force`<br>`--dry-run` |
 | `uninstall` | Remove scip-query-owned skill links, project hooks, and managed agent setup blocks | `--global`<br>`--project`<br>`--dry-run`<br>`--json` |
-| `watch` | Watch for file changes in the foreground and reindex automatically | `--debounce <ms>`<br>`--cooldown <ms>`<br>`--git-poll <ms>` |
+| `watch` | Watch in the foreground or manage the per-project background refresh service | `--daemon`<br>`--status`<br>`--stop`<br>`--debounce <ms>`<br>`--cooldown <ms>`<br>`--git-poll <ms>`<br>`--idle-timeout <ms>`<br>`--json` |
 | `status` | Show index status for this project | `--json`<br>`--capabilities` |
 
 <!-- END GENERATED COMMAND REFERENCE -->
@@ -178,3 +180,6 @@ even though its per-pair classification loop in `queries.coChange`
 candidate-pair count on a large repository. It now flows through `budgetedDbCommand` and
 `coChange` accepts a `scanLimit` option that truncates the (already priority-sorted) candidate
 pairs before classification, so the disclosed budget is truthful rather than cosmetic.
+The setup-scope follow-up rechecked this implementation citation; extracting
+shared hook outcome recording changed imports in the same runtime module but
+did not change the `co-change` budget boundary described here.

package/docs/REGEX_POLICY.md

@@ -11,7 +11,9 @@ Use parsers for structured inputs when the parser is available:
 
 Regex remains the right tool for flat machine-generated strings:
 
-- SCIP symbol encodings in `src/symbols/symbol-parser.ts`.
+- SCIP symbol encodings in `src/symbols/symbol-parser.ts`; when SCIP kind
+  metadata is available, detectors use it as the final callable/type/value
+  classification instead of treating symbol shape as sufficient proof.
 - SCIP row and descriptor filters in storage/query SQL when the pattern is static.
 - Path fragments and glob prefilters, followed by segment-aware matching when slash semantics matter.
 - Signature normalization in `src/queries/cleanup/similar-signatures.ts`.