scip-query 0.23.0 → 0.26.0

package/docs/COMMAND_REFERENCE.md

@@ -12,7 +12,7 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 
 Commands with `--json` share three structured modes: plain `--json` emits the stable public envelope, `--json --result-only` emits only the command payload, and `--json --compact` minifies either form for a program. Agents should prefer ordinary human output. See [CLI output modes](CLI_JSON_OUTPUT.md).
 
-Every command accepts `--output-page-size <characters>` and `--output-cursor <cursor>`. Run normally without choosing a page size: oversized human output stays readable text and prints one exact continuation command; oversized JSON prints the exact command that opts into versioned JSON page envelopes.
+Every command accepts `--output-page-size <characters>` and `--output-cursor <cursor>`. Run normally without choosing a page size: oversized human output prints a short preview and a complete temporary result file to read selectively. Pagination is opt-in; oversized JSON prints the exact command that opts into versioned JSON page envelopes.
 Cross-command evidence citations are off by default. With an explicit `SCIP_QUERY_SESSION`, a complete source unit, a byte-identical exact subset of a prior exact source read, or a graph unit/edge may be replaced by a visible receipt from the same index generation. Preview coverage never suppresses an exact unit; changed bytes, changed graph content, a new generation, or global `--reemit` force full evidence.
 
 ### Exploration control manual
@@ -23,10 +23,10 @@ The operator chooses the material question and deliberately selects a control. T
 |---|---|---|---|---|---|---|---|---|---|
 | locate | `search <exact-text>` | Where does this exact text occur in current project text, and which aligned compiler symbol owns each line? | One exact text literal or deliberately bounded regular expression; insert \`--\` before a literal that starts with a dash. | exact cardinality, bounded identities and source, and scope commands that recover withheld matches | Exact current-text cardinality and locations within reported text coverage; compiler ownership only where aligned. | Structural source ranking orders exact matches but does not establish task relevance. A literal co-occurrence does not establish a graph relationship. | `small` | outline: search locates exact text across files; outline enumerates compiler-owned constructs in one known file. | `evidence`, `inspect`, `code` |
 | locate | `outline <file>` | What symbols and nesting exist in this file? | One exact current project file path. | symbol names, nesting, and line ranges | Exact compiler-owned constructs and ranges when the file is indexed; no invented semantic overlay. | File ownership and nesting do not establish execution or task relevance. | `small` | search: outline enumerates constructs in one known file; search locates exact text across current project text. code: outline returns identities and ranges; code materializes exact source for selected identities. | `evidence`, `inspect`, `code` |
-| locate | `entrypoints [text]` | Which detected external roots or entry-surface candidates match this text? | Optional exact text to filter candidates; otherwise the current indexed repository. | entry symbols with files, confidence, evidence, and indexed caller counts | Source/compiler-grounded entry evidence and indexed caller counts; exported-only candidates remain candidates. | A package-public export or zero indexed callers is an entry candidate, not proof of runtime ingress. Entry classification does not establish that the callable executes. | `bounded` | entry-map: entrypoints locates possible external roots; entry-map traverses static calls from one selected root. search: entrypoints classifies callable roots; search only locates exact text and ownership. | `evidence`, `inspect`, `code` |
-| project | `evidence` | Which exact execution, runtime, data, state, temporal, contract, identity, ownership, or dependency relationships surround these referents? Which related source must be read only when graph evidence leaves a named implementation gap? | One or more exact symbol, file:line, or literal roots plus explicit family, direction, depth, and output bound. | batched exact selectors and typed graph relationships; compact endpoints with exact locations and follow-up commands; coverage and recoverable omissions; exact source-recovery command when source was requested with a graph projection; explicit ambiguity failure with exact rerun commands | Typed edges only to each registered provider ceiling within the explicitly selected projection and reported coverage. | The projection does not infer which relationships are relevant to the user task. Reference, dependency, data, state, temporal, contract, and identity edges do not become execution claims. | `bounded` | refs: refs enumerates direct reference sites; evidence traverses explicitly selected typed relationships. call-graph: call-graph specializes in static calls; evidence can combine execution with other selected families. value-flow: value-flow specializes in proved transfers; evidence projects bounded dataflow alongside other families. dependence-slice: dependence-slice computes a program-dependence slice; evidence performs bounded graph projection. | `inspect`, `code` |
+| locate | `entrypoints [text]` | Which detected external roots or entry-surface candidates match this text? | Optional exact text to filter candidates; otherwise the current indexed repository. | entry symbols with files, confidence, evidence, and observed static caller counts | Source/compiler-grounded entry evidence and observed static caller counts; exported-only candidates remain candidates. | A package-public export or zero indexed callers is an entry candidate, not proof of runtime ingress. Entry classification does not establish that the callable executes. | `bounded` | entry-map: entrypoints locates possible external roots; entry-map traverses static calls from one selected root. search: entrypoints classifies callable roots; search only locates exact text and ownership. | `evidence`, `inspect`, `code` |
+| project | `evidence` | Which exact execution, runtime, data, state, temporal, contract, identity, ownership, or dependency relationships surround these referents? Which related source must be read only when graph evidence leaves a named implementation gap? | One or more exact symbol, file:line, or literal roots plus explicit family, direction, depth, and output bound. | batched exact selectors and typed graph relationships; compact endpoints with exact locations and follow-up commands; coverage and recoverable omissions; exact source-recovery command when source was requested with a graph projection; explicit ambiguity failure with exact rerun commands | Typed edges only to each registered provider ceiling within the explicitly selected projection and reported coverage. | The projection does not infer which relationships are relevant to the user task. Reference, dependency, data, state, temporal, contract, and identity edges do not become execution claims. | `bounded` | refs: refs enumerates direct reference sites; evidence traverses explicitly selected typed relationships. call-graph: call-graph specializes in static calls; evidence can combine execution with other selected families. dependence-slice: dependence-slice computes a program-dependence slice; evidence performs bounded graph projection. | `inspect`, `code` |
 | read | `inspect` | Which related source units across several known text, symbol, or location anchors should be read together? | One or more exact text, symbol, or file:line selectors naming the unresolved behavior. | one ranked, deduplicated semantic packet plus exact selector cardinality and explicit expansion coverage | Complete current source for every materialized syntax unit; bounded selector and packet coverage remain explicit. | A source packet does not choose which implementation details are relevant to the user task. A reference mention does not establish executable reachability. | `potentially-large` | code: inspect batches bounded behavior or source gaps; code materializes complete exact source. evidence: inspect reads implementation units; evidence projects typed relationships without source. | - |
-| read | `code <selectors...>` | What exact source defines these symbols, ranges, or file surfaces? | One or more exact symbols, file:line ranges, or file paths. | per-selector resolution, complete definition source, exact ranges with statically attributed same-file call closure, file export surfaces, omitted-local ledgers, and line ranges | Exact current source bytes for every resolved selector, with omitted file-local constructs disclosed. | Source materialization does not establish callers, runtime reachability, or task relevance by itself. | `potentially-large` | inspect: code materializes complete exact source; inspect batches bounded behavior or source gaps. outline: code reads selected implementations; outline enumerates file structure without reading every body. | - |
+| read | `code <selectors...>` | What exact source defines these symbols, ranges, or file surfaces? | One or more exact symbols, file:line ranges, or file paths. | per-selector resolution, complete definition source, exact ranges, optional same-file call closure, file export surfaces, and omitted-local ledgers | Exact current source bytes for every resolved selector, with omitted file-local constructs disclosed. | Source materialization does not establish callers, runtime reachability, or task relevance by itself. | `potentially-large` | inspect: code materializes complete exact source; inspect batches bounded behavior or source gaps. outline: code reads selected implementations; outline enumerates file structure without reading every body. | - |
 
 ### Relationship question manual
 
@@ -61,8 +61,8 @@ The operator chooses the material question and deliberately selects a control. T
 | Locate exact roots | `search <exact-text>`, `outline <file>`, `fan-in [symbol]`, `entrypoints [text]` |
 | Project typed relationships | `evidence`, `entry-map <entry>` |
 | Read selected behavior/source | `inspect`, `code <selectors...>` |
-| Analyze declared result units | `stats`, `files <pattern>`, `methods <className>`, `refs <symbol>`, `trace <symbol>`, `deps <file>`, `rdeps <file>`, `system <module>`, `surface <module>`, `dead [scope]`, `hotspots`, `imports <file>`, `imported-by <symbol>`, `unused-imports <file>`, `members <symbol>`, `fan-out [file]`, `coupling [file1] [file2]`, `cycles`, `architecture`, `bottlenecks`, `isolated`, `by-kind <kind>`, `kind-counts`, `dependency-depth`, `hierarchy <symbol>`, `call-graph <symbol>`, `similar [symbol] [other]`, `similar-files [file]`, `react-component-duplicates [file]`, `react-hook-candidates [file]`, `react-large-component-pressure [file]`, `vue-component-duplicates [file]`, `vue-composable-candidates [file]`, `vue-large-view-pressure [file]`, `similar-chains`, `extract-candidates`, `locality-candidates [symbol-or-file]`, `affected <symbol>`, `change-surface <file>`, `cleanup-plan`, `co-change [file]`, `recent-duplicates`, `doc-drift [doc]`, `unused-params`, `incomplete-migration`, `context <target>`, `drift [module]`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `complexity-hotspots`, `self-audit`, `complexity <symbol>`, `reference-neighborhood <symbol>`, `value-flow <symbol>`, `dependence-slice <symbol-or-location>`, `reference-reachability <symbol>`, `redundant-reexports`, `duplicate-bodies`, `twin-drift`, `twin-ab <symbolA> <symbolB>`, `not-implemented`, `decorative-checkers`, `test-quality`, `similar-signatures`, `diff-impact`, `check-deps`, `capabilities`, `config-validate`, `doctor`, `status` |
-| Maintain repository/tool state | `reindex`, `augment-sources`, `augment-vue`, `session`, `tla <operation> [spec]`, `health`, `install-skills`, `init`, `suppress <id>`, `setup`, `setup-agent`, `uninstall`, `watch` |
+| Analyze declared result units | `review`, `stats`, `files <pattern>`, `methods <className>`, `refs <symbol>`, `deps <file>`, `rdeps <file>`, `system [module]`, `surface <module>`, `dead [scope]`, `hotspots`, `imports <file>`, `imported-by <symbol>`, `unused-imports <file>`, `members <symbol>`, `fan-out [file]`, `coupling [file1] [file2]`, `cycles`, `architecture`, `bottlenecks`, `by-kind <kind>`, `kind-counts`, `dependency-depth`, `hierarchy <symbol>`, `call-graph <symbol>`, `similar [symbol] [other]`, `similar-files [file]`, `react-component-duplicates [file]`, `react-hook-candidates [file]`, `react-large-component-pressure [file]`, `vue-component-duplicates [file]`, `vue-composable-candidates [file]`, `vue-large-view-pressure [file]`, `locality-candidates [symbol-or-file]`, `affected <symbol>`, `change-surface <file>`, `cleanup-plan`, `co-change [file]`, `recent-duplicates`, `doc-drift [doc]`, `unused-params`, `incomplete-migration`, `context <target>`, `drift [module]`, `passthrough-candidates`, `slice-cohesion [symbol]`, `complexity <symbol>`, `dependence-slice <file:line>`, `redundant-reexports`, `duplicate-bodies`, `twin-drift`, `not-implemented`, `decorative-checkers`, `test-quality`, `similar-signatures`, `diff-impact`, `check-deps`, `capabilities`, `config-validate`, `doctor`, `status` |
+| Maintain repository/tool state | `reindex`, `augment-sources`, `augment-vue`, `session`, `health`, `install-skills`, `init`, `suppress <id>`, `setup`, `setup-agent`, `uninstall`, `watch` |
 
 ### Typed relationship meanings
 
@@ -82,7 +82,7 @@ The operator chooses the material question and deliberately selects a control. T
 
 | Provider | Family / subtype | Directions | Support ceiling | Establishes | Does not establish |
 |---|---|---|---|---|---|
-| `indexed-program-identity` | `execution/call` | `incoming`, `outgoing`, `both` | `partial` | The source construct may call the resolved target. | Static may-call reachability does not prove that an invocation occurred at runtime. |
+| `indexed-program-identity` | `execution/call` | `incoming`, `outgoing`, `both` | `partial` | The source construct may call the resolved target. | Static may-call reachability does not prove that an invocation occurred at runtime. Compiler declaration identity does not resolve virtual dispatch, cross-file callable replacement, or runtime receiver identity. Candidate call edges preserve declaration leads; consult the invocation frontier for implementation resolution. A declaration reference is not an established implementation target. |
 | `indexed-program-identity` | `execution/result-callback` | `incoming`, `outgoing`, `both` | `partial` | The referenced callable can produce the result consumed by this path. | A callback relationship does not prove invocation order or runtime selection. |
 | `indexed-program-identity` | `contract/uses-contract-symbol` | `incoming`, `outgoing`, `both` | `exact` | The source construct refers to the identified contract symbol. | Contract identity does not prove runtime invocation or behavioral conformance. |
 | `indexed-program-identity` | `identity/references` | `incoming`, `outgoing`, `both` | `exact` | The occurrence resolves to the identified compiler-owned symbol. | A reference does not establish execution or value transfer. |
@@ -145,15 +145,24 @@ An unavailable frontier is a relationship class for which no registered analyzer
 | `general-interprocedural-value-flow` | `dataflow` | Whole-program definition-use flow through arbitrary calls and returns is unavailable. | Missing dataflow edges cannot establish that a value never crosses an unmodeled call. | `value-flow`, `dependence-slice`, `inspect`, `code` |
 | `heap-aliasing` | `dataflow`, `state` | Heap points-to and cross-instance alias analysis are unavailable. | Missing field or state edges cannot establish that two references never reach the same object. | `value-flow`, `dependence-slice`, `inspect`, `code` |
 | `exceptional-flow` | `execution`, `dataflow`, `temporal` | Interprocedural exception propagation and finally completion flow are unavailable. | Normal-path reachability and ordering do not establish behavior after a throw or rejection. | `dependence-slice`, `inspect`, `code` |
+| `dynamic-callable-dispatch` | `execution`, `dataflow` | General virtual dispatch and interprocedural replacement of callable values are unavailable. | A static declaration target does not establish a unique runtime implementation or all possible overrides. | `hierarchy`, `inspect`, `code` |
 | `reflection` | `execution`, `runtime`, `identity`, `dependencies` | Reflective lookup, dynamic loading, and name-computed invocation are unavailable without exact evidence. | Missing static edges cannot establish that a construct is unreachable through reflection. | `search`, `inspect`, `code` |
 | `generated-dispatch` | `execution`, `runtime`, `identity` | Dispatch tables or names created only by generated or unavailable source are unavailable. | Missing dispatch edges cannot establish that no generated consumer exists. | `search`, `inspect`, `code` |
 | `unsupported-framework-adapters` | `runtime`, `dataflow`, `state`, `temporal` | Framework runtime crossings without a registered source adapter are unavailable. | Missing boundary edges cannot establish that no producer, consumer, state effect, or ordering exists. | `search`, `inspect`, `code` |
 
+### Health
+
+| Command | Description | Cost | Closes disclosed gaps with | Options |
+|---|---|---|---|---|
+| `review` | Review current TS/JS changes against a Git commit, including new and untracked functions | variable | `inspect`, `code` | `--base <ref>`<br>`--coverage <path>`<br>`-s, --scope <path>`<br>`--include-tests`<br>`--include-references`<br>`--include-generated`<br>`--max-files <n>`<br>`--limit <n>`<br>`--full`<br>`--check`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `complexity <symbol>` | Per-symbol complexity: branches, cyclomatic estimate, fan-in/out, callees | variable | `inspect`, `code` | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `health` | Find concrete TS/JS complexity, duplication, and dependency issues without an index | variable | - | `-s, --scope <path>`<br>`--full`<br>`--indexed`<br>`--coverage <path>`<br>`--include-tests`<br>`--include-references`<br>`--include-generated`<br>`--max-files <n>`<br>`--limit <n>`<br>`--check`<br>`--baseline`<br>`--write-baseline`<br>`--json`<br>`--result-only`<br>`--compact` |
+
 ### Indexing
 
 | Command | Description | Cost | Closes disclosed gaps with | Options |
 |---|---|---|---|---|
-| `reindex` | Index the codebase and convert to SQLite | variable | - | `-l, --language <lang>`<br>`--pnpm-workspaces`<br>`--force`<br>`--allow-partial`<br>`--allow-expensive-rebuild`<br>`--trust-project-tools`<br>`--install-missing`<br>`--indexer-concurrency <n>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `reindex` | Index the codebase and convert to SQLite | variable | - | `-l, --language <lang>`<br>`--force`<br>`--allow-partial`<br>`--allow-expensive-rebuild`<br>`--trust-project-tools`<br>`--install-missing`<br>`--indexer-concurrency <n>`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `augment-sources` | Add source files skipped by upstream SCIP indexers to the SQLite documents table | variable | - | - |
 | `augment-vue` | Add compiler-resolved Vue SFC references to the SQLite index using Volar | variable | - | `--project <tsconfig>` |
 
@@ -169,28 +178,24 @@ An unavailable frontier is a relationship class for which no registered analyzer
 |---|---|---|---|---|
 | `files <pattern>` | Find current project files matching a path pattern | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
 | `session` | Show evidence already delivered in this agent exploration session | variable | - | `--reset` |
-| `inspect` | Batch related searches, symbols, and source locations into one deduplicated source packet | potentially-large | - | `--search <text>`<br>`--symbol <symbol>`<br>`--at <file:line>`<br>`-s, --scope <path>`<br>`-C, --context <n>`<br>`-n, --limit <n>`<br>`--max-units <n>`<br>`--max-characters <n>`<br>`--view <view>`<br>`--allow-large-source`<br>`--allow-large-behavior`<br>`--unit-lines <n>`<br>`--total-lines <n>`<br>`--include <part>`<br>`--evidence-budget <channel=n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `search <exact-text>` | Count current project text matches and preview a bounded, recoverable identity and source manifest | small | `evidence`, `inspect`, `code` | `-s, --scope <path>`<br>`-C, --context <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--regexp`<br>`-i, --ignore-case`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `inspect` | Batch related searches, symbols, and source locations into one deduplicated source packet | potentially-large | - | `--bindings`<br>`--search <text>`<br>`--symbol <symbol>`<br>`--at <file:line>`<br>`-s, --scope <path>`<br>`-C, --context <n>`<br>`-n, --limit <n>`<br>`--max-units <n>`<br>`--max-characters <n>`<br>`--view <view>`<br>`--allow-large-source`<br>`--allow-large-behavior`<br>`--unit-lines <n>`<br>`--total-lines <n>`<br>`--include <part>`<br>`--evidence-budget <channel=n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `search <exact-text>` | Find current text matches with exact locations and optional compiler owners | small | `evidence`, `inspect`, `code` | `-s, --scope <path>`<br>`-C, --context <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--regexp`<br>`-i, --ignore-case`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `methods <className>` | List methods of one exactly resolved class; ambiguity and missing targets fail explicitly | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
 | `refs <symbol>` | Find all files referencing a symbol | bounded | `inspect`, `code` | `--full`<br>`-n, --limit <n>`<br>`--cursor <cursor>`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `trace <symbol>` | Trace a symbol: definition + all references | bounded | `inspect`, `code` | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `evidence` | Traverse selected typed relationships around exact referents; recover source separately when needed | bounded | `inspect`, `code` | `--symbol <symbol>`<br>`--at <file:line>`<br>`--search <literal>`<br>`--view <view>`<br>`--edge <family>`<br>`--direction <direction>`<br>`--subtype <subtype>`<br>`--connecting`<br>`--inventory-only`<br>`--fold <id>`<br>`--depth <n>`<br>`--max-edges <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `evidence` | Traverse selected typed relationships around exact referents; recover source separately when needed | bounded | `inspect`, `code` | `--symbol <symbol>`<br>`--at <file:line>`<br>`--search <literal>`<br>`--view <view>`<br>`--edge <family>`<br>`--direction <direction>`<br>`--subtype <subtype>`<br>`--connecting`<br>`--detail`<br>`--inventory-only`<br>`--fold <id>`<br>`--depth <n>`<br>`--max-edges <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `deps <file>` | Files this file depends on (internal) | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
 | `rdeps <file>` | Files that depend on this file/module | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
-| `system <module>` | One-hop module summary: matched files, documented symbols, and file reference dependencies | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+| `system [module]` | Module files and dependencies; --source adds a first-use inventory, exports, policy and findings without an index | bounded | `inspect`, `code` | `--source`<br>`--include-tests`<br>`--include-references`<br>`--include-generated`<br>`--max-files <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `surface <module>` | What symbols consumers actually use from this module | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
 | `imports <file>` | What symbols does this file import? | variable | `inspect`, `code` | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `imported-by <symbol>` | Which files import this symbol? | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+| `imported-by <symbol>` | Which files import this symbol? | variable | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
 | `outline <file>` | Tree view of symbols in a file, with line ranges | small | `evidence`, `inspect`, `code` | `--signatures`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `members <symbol>` | All children of a symbol (methods, fields, nested types) | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
 | `by-kind <kind>` | Find symbols by SCIP kind (class, interface, enum, function, etc.) | variable | `inspect`, `code` | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `kind-counts` | Histogram of symbol kinds in the codebase | bounded | `inspect`, `code` | `-s, --scope <path>`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `hierarchy <symbol>` | Show a symbol's ancestry chain (method → class → module) | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
-| `code <selectors...>` | Read exact definitions, ranges with local call closure, or file export surfaces | potentially-large | - | `-C, --context <n>`<br>`--members <exported|all>`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `reference-neighborhood <symbol>` | Show definition/reference sites and incoming/outgoing static calls without value-flow claims | variable | `inspect`, `code` | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `value-flow <symbol>` | Show only proved argument/parameter and bounded static-value transfers around a symbol | variable | `inspect`, `code` | `--depth <n>`<br>`--max-edges <n>`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `dependence-slice <symbol-or-location>` | Directional slice over proved data/control dependencies with explicit supporting call edges | variable | `inspect`, `code` | `--forward`<br>`--depth <n>`<br>`--max-edges <n>`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `reference-reachability <symbol>` | Traverse legacy callee or reference-owner reachability without calling it a program slice | variable | `inspect`, `code` | `--forward`<br>`--depth <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `hierarchy <symbol>` | Show indexed lexical owners of a symbol (method → class → module) | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+| `code <selectors...>` | Read exact definitions, line ranges, or file export surfaces | potentially-large | - | `-C, --context <n>`<br>`--bindings`<br>`--local-calls`<br>`--members <exported|all>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `dependence-slice <file:line>` | Slice one variable occurrence through function-local value and control dependencies | variable | `inspect`, `code` | `--forward`<br>`--variable <name>`<br>`--column <n>`<br>`--depth <n>`<br>`--max-edges <n>`<br>`--json`<br>`--result-only`<br>`--compact` |
 
 ### Cleanup
 
@@ -198,7 +203,6 @@ An unavailable frontier is a relationship class for which no registered analyzer
 |---|---|---|---|---|
 | `dead [scope]` | Find repository-dead code, file-internal symbols, and implicit-usage signals | variable | `inspect`, `code` | `--min-loc <n>`<br>`--include-tests`<br>`--skip-barrels`<br>`--include-members`<br>`--only-dead`<br>`--only-internal`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `unused-imports <file>` | Find imports not referenced in the same file | variable | `inspect`, `code` | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `isolated` | Find completely orphaned symbols (no references at all) | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `similar [symbol] [other]` | Find heuristic function similarity candidates from callee fingerprints | variable | `inspect`, `code` | `--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`<br>`--result-only`<br>`--compact` |
 | `similar-files [file]` | Find heuristic similar-file candidates from dependency profiles | variable | `inspect`, `code` | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-deps <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `react-component-duplicates [file]` | Find heuristic duplicated React component structure candidates from JSX tags, props, events, and bindings | variable | `inspect`, `code` | `--min-similarity <n>`<br>`--min-tokens <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
@@ -207,32 +211,27 @@ An unavailable frontier is a relationship class for which no registered analyzer
 | `vue-component-duplicates [file]` | Find heuristic duplicated Vue component structure candidates from template tags, bindings, slots, and directives | variable | `inspect`, `code` | `--min-similarity <n>`<br>`--min-tokens <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `vue-composable-candidates [file]` | Find heuristic Vue composable extraction candidates from shared state, effects, requests, and template bindings | variable | `inspect`, `code` | `--min-similarity <n>`<br>`--min-shared-behaviors <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `vue-large-view-pressure [file]` | Find heuristic large Vue view pressure candidates from template, script, style, and external script line counts | variable | `inspect`, `code` | `--min-total-lines <n>`<br>`--min-template-lines <n>`<br>`--min-script-lines <n>`<br>`--min-style-lines <n>`<br>`--review-thresholds`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `similar-chains` | Find heuristic similar-chain candidates from dependency flows | variable | `inspect`, `code` | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-length <n>`<br>`--max-length <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `extract-candidates` | Find heuristic extraction candidates from isolated callee clusters | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--min-callees <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `locality-candidates [symbol-or-file]` | Find directory-locality and ancestry candidates from consumer ownership | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-consumers <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `cleanup-plan` | Ordered, batched deletion plan: graph-fact dead code plus the cascade candidates it unlocks | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--max-depth <n>`<br>`--verify`<br>`--patch`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `recent-duplicates` | Directional duplicate candidates: recent code that re-implements established callable, React, or Vue code | variable | `inspect`, `code` | `--window <n>`<br>`--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `recent-duplicates` | Similarity candidates in recently added files, oriented by file age; function creation time is not known | variable | `inspect`, `code` | `--window <n>`<br>`--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `doc-drift [doc]` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | variable | `inspect`, `code` | `-n, --limit <n>`<br>`--min-coupling <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `unused-params` | Speculative-generality candidates: trailing parameters no body ever uses (TS/JS) | variable | `inspect`, `code` | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `drift [module]` | Detect drift candidates: unused imports and declared architecture violations; pass --architecture for boundary context | variable | `inspect`, `code` | `--min-deviation <n>`<br>`--patterns`<br>`--architecture`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `wrapper-candidates` | Find heuristic wrapper candidates only called by one consumer (high false-positive rate on codebases with intentional layering/ambient types — treat as exploration, not findings) | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--max-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `passthrough-candidates` | Find heuristic passthrough candidates that forward to one callee | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--max-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `stale-abstractions` | Find heuristic stale abstraction candidates with 0-1 consumers (high false-positive rate on codebases with intentional layering/ambient types — treat as exploration, not findings) | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--include-low-confidence`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `complexity-hotspots` | Find heuristic complexity hotspot candidates from LOC x fan-in x fan-out | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `redundant-reexports` | Find barrel re-exports that nobody imports through | variable | `inspect`, `code` | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `slice-cohesion [symbol]` | Find low-cohesion candidates from backward slices: outputs whose statements never meet are separate local computations | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--min-statements <n>`<br>`--min-cluster <n>`<br>`-n, --limit <n>`<br>`--scan-limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `redundant-reexports` | Find re-export candidates with no resolved local source imports or re-exports; external use is unknown | variable | `inspect`, `code` | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `duplicate-bodies` | Find exact duplicate small-body candidates across files | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--max-loc <n>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `twin-drift` | Twin drift candidates: same-name (or near-name) functions across files with diverged bodies | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-similarity <n>`<br>`--include-homonyms`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `twin-ab <symbolA> <symbolB>` | Generate a behavioral A/B scaffold comparing two same-concept twins (cleanup integrity scenario) — a ready-to-fill vitest file, not an auto-executor | bounded | `inspect`, `code` | `--out <path>`<br>`--force`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `not-implemented` | Reachable placeholder stub candidates (throw-stub, TODO+return-default, empty body) — production callers can actually reach these; an unreachable stub is dead's job, not this one's | variable | `inspect`, `code` | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `decorative-checkers` | Decorative checker candidates: validate*/verify*/check*/assert*/is*/has* callables with no reachable failure exit anywhere in their body | variable | `inspect`, `code` | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `not-implemented` | Placeholder candidates with observed consumer or entry-surface evidence: throw-stub, TODO plus default return, or empty body | variable | `inspect`, `code` | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `decorative-checkers` | Checker candidates lacking detected explicit failure syntax; implicit exceptions and property effects are not proved absent | variable | `inspect`, `code` | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `test-quality` | Test-quality candidates: assertion-free it/test bodies, a skipped-test ledger with git-blame age, and mock-echo tests that assert the same literal they stubbed into a mock | variable | `inspect`, `code` | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--rot-days <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `similar-signatures` | Find functions with near-identical type signatures (same shape) | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--max-shape-frequency <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `similar-signatures` | Group functions by normalized signature text; shared type identity or responsibility is not established | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--max-shape-frequency <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 
 ### Graph
 
 | Command | Description | Cost | Closes disclosed gaps with | Options |
 |---|---|---|---|---|
-| `hotspots` | Rank symbols by cross-file reference count; a reference metric, not runtime contention | variable | `inspect`, `code` | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `hotspots` | Rank symbols by referencing chunks, or incoming evidence rows when SCIP mentions are unavailable | variable | `inspect`, `code` | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `fan-in [symbol]` | Count files referencing an exact symbol; top JSON rows include exact symbol identity | small | `evidence`, `inspect`, `code` | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `fan-out [file]` | How many external symbols a file uses (or top fan-out across codebase) | variable | `inspect`, `code` | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `coupling [file1] [file2]` | Count shared-symbol coupling between two files, or rank file pairs by that metric | variable | `inspect`, `code` | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
@@ -254,31 +253,17 @@ An unavailable frontier is a relationship class for which no registered analyzer
 | `incomplete-migration` | Partially-completed extraction candidates: new helpers in the diff wired into some sites while similar un-migrated sites remain | variable | `inspect`, `code` | `--base <ref>`<br>`--min-containment <n>`<br>`--max-helpers <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `diff-impact` | Map changed symbols and downstream consumers from the current git diff | variable | `inspect`, `code` | `--base <ref>`<br>`--json`<br>`--result-only`<br>`--compact` |
 
-### Formal Models
-
-| Command | Description | Cost | Closes disclosed gaps with | Options |
-|---|---|---|---|---|
-| `tla <operation> [spec]` | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | variable | - | `--map <file>`<br>`--config <file>`<br>`--checker <mode>`<br>`--tla-tools <jar>`<br>`--apalache <binary>`<br>`--length <n>`<br>`--timeout-ms <n>`<br>`--trace <file>`<br>`--next <operator>`<br>`--coverage`<br>`--allow-unknown`<br>`--out <path>`<br>`--module-name <name>`<br>`--force`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-
 ### Exploration
 
 | Command | Description | Cost | Closes disclosed gaps with | Options |
 |---|---|---|---|---|
-| `context <target>` | Compiler-backed context for a symbol, file, or module | bounded | `inspect`, `code` | `--impact-depth <n>`<br>`--slice-depth <n>`<br>`-s, --scope <path>`<br>`-n, --limit <n>`<br>`--detail`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-
-### Health
-
-| Command | Description | Cost | Closes disclosed gaps with | Options |
-|---|---|---|---|---|
-| `self-audit` | Score cheap evidence paths against the best available semantic/source oracle on sampled symbols | variable | `inspect`, `code` | `--samples <n>`<br>`-s, --scope <path>`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `complexity <symbol>` | Per-symbol complexity: branches, cyclomatic estimate, fan-in/out, callees | variable | `inspect`, `code` | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
-| `health` | Composite repository health report with React, Vue, and general cleanup findings | variable | - | `-s, --scope <path>`<br>`--full`<br>`--baseline`<br>`--write-baseline`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `context <target>` | Compiler-backed context for a symbol, file, or module | bounded | `inspect`, `code` | `--impact-depth <n>`<br>`-s, --scope <path>`<br>`-n, --limit <n>`<br>`--detail`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
 
 ### Maintenance
 
 | Command | Description | Cost | Closes disclosed gaps with | Options |
 |---|---|---|---|---|
-| `install-skills` | Install skills (scip-query, scip-explore, scip-plan, scip-setup, scip-integrity-audit) into Claude Code, Codex, and shared agent roots | variable | - | - |
+| `install-skills` | Install the six agent workflows into Claude Code, Codex, and shared agent roots | variable | - | `--all` |
 | `check-deps` | Check whether scip-query and the detected language indexers are runnable | bounded | `inspect`, `code` | - |
 | `capabilities` | Report which mapping and analysis capabilities are available in this project | bounded | `inspect`, `code` | `--matrix`<br>`--json`<br>`--result-only`<br>`--compact` |
 | `init` | Create a .scipquery.json configuration file for this project | variable | - | - |

package/docs/CURRENT_COMMANDS.md

@@ -0,0 +1,123 @@
+# Current command inventory
+
+The current registry contains **86 commands: 81 public controls and 5 internal transport/worker controls**. Eleven commands were retired from the 97-control inventory used at the start of this sweep. TLA and older removals predate that inventory.
+
+A command is a named CLI operation that accepts selectors or options and returns repository observations or performs a defined maintenance action. An observed relationship records evidence connecting concrete files or symbols. A candidate is a possible cleanup or design issue inferred from a stated pattern; its existence does not prove that refactoring will preserve behavior or improve the design.
+
+For first-use architecture assessment, use `system --source`; for current-source issue scanning, use `health`. Use `search`/`outline`/`code`/`inspect`/`evidence` for the facts a task needs, and `review`, `diff-impact` and applicable architecture checks after changes. The [command decision guide](../skills/scip-query/references/command-guide.md) maps every public control to a question, index requirement and limit. Full flags and examples are in [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md); per-command decisions and test scope are in the [audit ledger](../benchmarks/command-contracts/2026-09-05/ledger.json).
+
+The audit reviews contracts and tests known counterexamples. It does not establish universal accuracy across every language, framework or runtime convention. In particular, directory proximity and shared names do not prove conceptual ownership, candidate duplication does not prove interchangeability, and static relationships do not prove runtime reachability. CRAP requires source-matched test coverage; absent coverage is reported as unavailable.
+
+## Public controls
+
+| Command | Purpose |
+| --- | --- |
+| `review` | Review current TS/JS changes against a Git commit, including new and untracked functions |
+| `reindex` | Index the codebase and convert to SQLite |
+| `augment-sources` | Add source files skipped by upstream SCIP indexers to the SQLite documents table |
+| `augment-vue` | Add compiler-resolved Vue SFC references to the SQLite index using Volar |
+| `stats` | Show index statistics |
+| `files` | Find current project files matching a path pattern |
+| `session` | Show evidence already delivered in this agent exploration session |
+| `inspect` | Batch related searches, symbols, and source locations into one deduplicated source packet |
+| `search` | Count current project text matches and preview a bounded, recoverable identity and source manifest |
+| `methods` | List methods of one exactly resolved class; ambiguity and missing targets fail explicitly |
+| `refs` | Find all files referencing a symbol |
+| `evidence` | Traverse selected typed relationships around exact referents; recover source separately when needed |
+| `deps` | Files this file depends on (internal) |
+| `rdeps` | Files that depend on this file/module |
+| `system` | Indexed module summary; `--source` adds a current TS/JS module inventory, export declarations, imports, consumers, policy and findings without an index |
+| `surface` | What symbols consumers actually use from this module |
+| `dead` | Find repository-dead code, file-internal symbols, and implicit-usage signals |
+| `hotspots` | Rank symbols by referencing chunks, or incoming evidence rows when SCIP mentions are unavailable |
+| `imports` | What symbols does this file import? |
+| `imported-by` | Which files import this symbol? |
+| `unused-imports` | Find imports not referenced in the same file |
+| `outline` | Tree view of symbols in a file, with line ranges |
+| `members` | All children of a symbol (methods, fields, nested types) |
+| `fan-in` | Count files referencing an exact symbol; top JSON rows include exact symbol identity |
+| `fan-out` | How many external symbols a file uses (or top fan-out across codebase) |
+| `coupling` | Count shared-symbol coupling between two files, or rank file pairs by that metric |
+| `cycles` | Find every cyclic file-dependency component and show one deterministic witness for each |
+| `architecture` | Evaluate project-owned architectural boundaries and dependency rules |
+| `bottlenecks` | Rank coordination hubs by incoming evidence files × outgoing cross-file callable targets |
+| `by-kind` | Find symbols by SCIP kind (class, interface, enum, function, etc.) |
+| `kind-counts` | Histogram of symbol kinds in the codebase |
+| `dependency-depth` | Find longest paths through the SCC-condensed file dependency graph |
+| `hierarchy` | Show indexed lexical owners of a symbol (method → class → module) |
+| `entrypoints` | Find callables where control may enter from outside the indexed call graph |
+| `entry-map` | Map the complete indexed call graph from one detected entry point, collapsed by file |
+| `call-graph` | Show static may-call edges with exact/candidate evidence and explicit blind spots |
+| `similar` | Find heuristic function similarity candidates from callee fingerprints |
+| `similar-files` | Find heuristic similar-file candidates from dependency profiles |
+| `react-component-duplicates` | Find heuristic duplicated React component structure candidates from JSX tags, props, events, and bindings |
+| `react-hook-candidates` | Find heuristic React hook extraction candidates from shared state, effects, requests, and handlers |
+| `react-large-component-pressure` | Find heuristic large React component pressure candidates from component lines, JSX structure, and hook behavior |
+| `vue-component-duplicates` | Find heuristic duplicated Vue component structure candidates from template tags, bindings, slots, and directives |
+| `vue-composable-candidates` | Find heuristic Vue composable extraction candidates from shared state, effects, requests, and template bindings |
+| `vue-large-view-pressure` | Find heuristic large Vue view pressure candidates from template, script, style, and external script line counts |
+| `locality-candidates` | Find directory-locality and ancestry candidates from consumer ownership |
+| `affected` | Conservative reverse caller/reference closure of symbols that may be impacted by a change |
+| `change-surface` | Pre-change briefing: consumers, published API, operational roots, and explained change risk |
+| `cleanup-plan` | Ordered, batched deletion plan: graph-fact dead code plus the cascade candidates it unlocks |
+| `co-change` | Files that change together in git history without a dependency edge — hidden coupling candidates |
+| `recent-duplicates` | Similarity candidates in recently added files, oriented by file age; function creation time is not known |
+| `doc-drift` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped |
+| `unused-params` | Speculative-generality candidates: trailing parameters no body ever uses (TS/JS) |
+| `incomplete-migration` | Partially-completed extraction candidates: new helpers in the diff wired into some sites while similar un-migrated sites remain |
+| `context` | Compiler-backed context for a symbol, file, or module |
+| `drift` | Detect drift candidates: unused imports and declared architecture violations; pass --architecture for boundary context |
+| `passthrough-candidates` | Find heuristic passthrough candidates that forward to one callee |
+| `slice-cohesion` | Find low-cohesion candidates from backward slices: outputs whose statements never meet are separate local computations |
+| `code` | Read exact definitions, line ranges, or file export surfaces |
+| `complexity` | Per-symbol complexity: branches, cyclomatic estimate, fan-in/out, callees |
+| `dependence-slice` | Slice one variable occurrence through function-local value and control dependencies |
+| `redundant-reexports` | Find re-export candidates with no resolved local source imports or re-exports; external use is unknown |
+| `duplicate-bodies` | Find exact duplicate small-body candidates across files |
+| `twin-drift` | Twin drift candidates: same-name (or near-name) functions across files with diverged bodies |
+| `not-implemented` | Placeholder candidates with observed consumer or entry-surface evidence: throw-stub, TODO plus default return, or empty body |
+| `decorative-checkers` | Checker candidates lacking detected explicit failure syntax; implicit exceptions and property effects are not proved absent |
+| `test-quality` | Test-quality candidates: assertion-free it/test bodies, a skipped-test ledger with git-blame age, and mock-echo tests that assert the same literal they stubbed into a mock |
+| `similar-signatures` | Group functions by normalized signature text; shared type identity or responsibility is not established |
+| `diff-impact` | Map changed symbols and downstream consumers from the current git diff |
+| `health` | Find concrete TS/JS complexity, duplication, and dependency issues without an index |
+| `install-skills` | Install the six agent workflows into Claude Code, Codex, and shared agent roots |
+| `check-deps` | Check whether scip-query and the detected language indexers are runnable |
+| `capabilities` | Report which mapping and analysis capabilities are available in this project |
+| `init` | Create a .scipquery.json configuration file for this project |
+| `config-validate` | Validate .scipquery.json, structured suppressions, architecture, and coupling groups |
+| `suppress` | Record an accepted finding under .scipquery/suppressions with a required reason |
+| `doctor` | Diagnose configuration, index freshness, dependencies, and project capabilities |
+| `setup` | Install skills, write agent guidance, refresh the index, and report readiness |
+| `setup-agent` | Write concise scip-query mapping and cleanup guidance to AGENTS.md and CLAUDE.md |
+| `uninstall` | Remove selected scip-query-owned skills or project guidance |
+| `watch` | Watch in the foreground or manage the project refresh service |
+| `status` | Show index status for this project |
+
+## Internal controls
+
+These serve continuation or worker protocols, rather than additional exploration questions.
+
+| Command | Purpose |
+| --- | --- |
+| `continue` | Continue an immutable output snapshot |
+| `hook-architecture-stop` | Internal architecture-only Stop hook |
+| `__diff-impact-batch` | Internal diff-impact batch worker |
+| `__health-phase` | Internal health phase worker |
+| `__health-semantic-prewarm` | Internal health semantic prewarm worker |
+
+## Retired in this sweep
+
+- `trace`: Retire overlapping definition/reference CLI and service fast path; refs/code/inspect/evidence cover its work without the unsupported all-call predicate guarantee. Internal source assembly remains for context/inspect, ineligible for absence and universal callsite claims.
+- `reference-neighborhood`: remove
+- `value-flow`: Remove redundant dataflow projection wrapper. Its only-proved description contradicts candidate edges passed through from graphEvidence. Retain evidence --edge dataflow with explicit direction/depth and dependence-slice.
+- `reference-reachability`: remove
+- `isolated`: Remove: unused-code subset with no distinct action; overlapping health counts, and missing same-file strict callers. Use dead and explicit evidence projections.
+- `similar-chains`: Scores filtered dependency paths but renders original paths/divergence offsets; undisclosed 500-chain and limit*10 pair enumeration. Explicit dependency evidence and dependency-depth provide actual structural facts.
+- `extract-candidates`: Occurrence-range regionLocalFlow cannot prove extraction inputs/outputs across branches, scopes and aliases; recommendations assert exact parameter counts. Use dependence-slice and slice-cohesion within their disclosed local model.
+- `wrapper-candidates`: remove
+- `stale-abstractions`: remove
+- `complexity-hotspots`: remove
+- `self-audit`: Measures file-set agreement between overlapping evidence providers, not symbol correctness; two wrong targets in the same file can agree. Independent known-answer tests replace the accuracy claim.
+
+Use ordinary invocation to check that a command exists. Commander may display root help for an unknown name followed by `--help`; that exit is not command validation. Every retirement is checked with an ordinary invocation.

package/docs/DETECTOR_EVIDENCE_CONTRACTS.md

@@ -12,26 +12,6 @@ The symbol has no visible repository reference after entry, framework, and roote
 - Does not establish: Absence of visible references does not prove absence of reflection, generated dispatch, or external use.
 - Recover with: `scip-query evidence --symbol <symbol> --edge execution --edge runtime --edge identity --direction both --depth 2 --max-edges 100`
 
-## isolated
-
-The callable has no visible non-self caller or callee after entry, framework, and rooted-symbol exclusions.
-
-- Calibration: `mixed`; provider coverage: `partial`.
-- Relations: `execution/call` (exact), `identity/references` (exact).
-- Structural evidence: entry-surface exclusions; framework contract exclusions; source fallback callers.
-- Does not establish: Visible graph isolation does not establish runtime unreachability through reflection or generated dispatch.
-- Recover with: `scip-query evidence --symbol <symbol> --edge execution --edge runtime --edge identity --direction both --depth 2 --max-edges 100`
-
-## wrapper-candidates
-
-A small callable has one visible consumer and wrapper-shaped delegation, after boundary evidence is disclosed.
-
-- Calibration: `candidate`; provider coverage: `partial`.
-- Relations: `execution/call` (exact), `ownership/contains` (exact).
-- Structural evidence: callable body shape; public and runtime-boundary signals; consumer fan-in.
-- Does not establish: Wrapper shape does not prove that an API, ownership, observability, or compatibility boundary is unnecessary.
-- Recover with: `scip-query inspect --symbol <symbol> --view behavior`
-
 ## passthrough-candidates
 
 A small callable visibly forwards to one callee, with public-facade and boundary signals disclosed.
@@ -42,26 +22,6 @@ A small callable visibly forwards to one callee, with public-facade and boundary
 - Does not establish: Literal forwarding does not prove the callable has no contract, naming, policy, or compatibility role.
 - Recover with: `scip-query inspect --symbol <symbol> --view behavior`
 
-## stale-abstractions
-
-A type-like abstraction has zero or one visible real consumer after re-export and ownership distinctions.
-
-- Calibration: `mixed`; provider coverage: `partial`.
-- Relations: `identity/references` (exact), `ownership/contains` (exact).
-- Structural evidence: definition kind; barrel-only consumer distinction; defining-file usage.
-- Does not establish: Low visible consumer count does not prove a public contract or runtime-registered type is obsolete.
-- Recover with: `scip-query evidence --symbol <symbol> --edge identity --edge ownership --edge contract --direction both --depth 2 --max-edges 100`
-
-## complexity-hotspots
-
-A callable concentrates local branch/control pressure and graph fan-in or fan-out.
-
-- Calibration: `mixed`; provider coverage: `partial`.
-- Relations: `execution/predicate-consequence` (exact), `execution/call` (exact).
-- Structural evidence: AST branch count or disclosed regex fallback; call fan-in; callee count.
-- Does not establish: Structural complexity does not establish runtime frequency, latency, defect density, or a required refactor.
-- Recover with: `scip-query inspect --symbol <symbol> --view behavior`
-
 ## decorative-checkers
 
 A checker-shaped callable lacks a visible failure terminal directly or through one resolved delegate.

package/docs/DETECTOR_GUIDE.md

@@ -13,21 +13,27 @@ scip-query health --full
 
 The health report combines graph structure, duplication, drift, complexity,
 history, suppressions, coverage contracts, and React and Vue analyses. Its
-score is a summary, not proof of correctness.
+score is a summary, not proof of correctness. The `Input:` line under the
+file and symbol counts names the index generation and the git commit,
+branch, and uncommitted-path count the report was computed from
+(`provenance` in `health --json`); compare two reports only when that line
+matches, because a repository change and a detector change move the same
+numbers.
 
 ## Focused detector families
 
-| Concern | Commands |
-| --- | --- |
-| Exact or near duplication | `duplicate-bodies`, `similar`, `recent-duplicates` |
-| Parallel implementations | `twin-drift`, `incomplete-migration`, `drift` |
-| Unused or disconnected code | `dead`, `isolated`, `unused-params` |
-| Excess indirection | `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `redundant-reexports` |
-| Change pressure | `complexity-hotspots`, `co-change`, `cycles` |
-| Documentation | `doc-drift` |
-| React | `react-component-duplicates`, `react-hook-candidates`, `react-large-component-pressure` |
-| Vue | `vue-component-duplicates`, `vue-composable-candidates`, `vue-large-view-pressure` |
-| Team structure policy | `architecture` |
+| Concern                     | Commands                                                                                    |
+| --------------------------- | ------------------------------------------------------------------------------------------- |
+| Exact or near duplication   | `duplicate-bodies`, `similar`, `recent-duplicates`                                          |
+| Parallel implementations    | `twin-drift`, `incomplete-migration`, `drift`                                               |
+| Unused or disconnected code | `dead`, `isolated`, `unused-params`                                                         |
+| Excess indirection          | `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `redundant-reexports` |
+| Extraction seams            | `extract-candidates`, `slice-cohesion`                                                      |
+| Change pressure             | `complexity-hotspots`, `co-change`, `cycles`                                                |
+| Documentation               | `doc-drift`                                                                                 |
+| React                       | `react-component-duplicates`, `react-hook-candidates`, `react-large-component-pressure`     |
+| Vue                         | `vue-component-duplicates`, `vue-composable-candidates`, `vue-large-view-pressure`          |
+| Team structure policy       | `architecture`                                                                              |
 
 Run focused commands through the `scip-query` CLI. Add `--full` only when that
 command supports it and exhaustive command coverage can change the decision.
@@ -44,3 +50,40 @@ command supports it and exhaustive command coverage can change the decision.
 Suppress a false or accepted finding with `scip-query suppress <id>` and a
 specific reason. A suppression addresses one finding; it must not disable an
 unrelated detector family.
+
+## Policy exclusions
+
+Some rows match a detector's pattern because a convention demands the
+match, not because anyone copied or wrapped anything. Detectors remove those
+rows from the counts `health` scores and disclose the removal instead of
+hiding it, under `Policy exclusions` in the text report and `policyExclusions`
+in `health --json`. An excluded row is still listed by its focused command
+(often at support tier), so a reviewer who disagrees with the policy can
+still find it.
+
+| Detector                                                                                | Excluded by policy                                                                                                                                                                                                                                                                |
+| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `react-component-duplicates`, `react-hook-candidates`, `react-large-component-pressure` | components in test files; pairs of vendored UI-kit primitives (the shadcn `components.json` `aliases.ui` directory or a `components/ui` directory); hook-versus-component pairs; loading placeholders that share only a skeleton primitive                                        |
+| `react-component-duplicates`                                                            | two framework route entries whose JSX overlaps (support tier: routing scaffolding); shared _behavior_ between route entries still counts                                                                                                                                          |
+| `react-component-duplicates`, `react-hook-candidates`                                   | an intercepting route and its target are kept, with the recommendation to render one shared view                                                                                                                                                                                  |
+| `react-hook-candidates`                                                                 | pairs whose overlap is only generic React or data-fetching mechanics (`useState`, `useMutation`, `.mutate()`, `useRouter`)                                                                                                                                                        |
+| `wrapper-candidates`                                                                    | constructors; single-consumer callables whose body is not exactly one call with plain-value arguments (a preparatory statement, a callback, a nested call, or a literal the body builds makes it `bodyShape: helper`, signal tier)                                                |
+| `duplicate-bodies`                                                                      | duplicate members that are constructors, test-file bodies, route-file verb exports, or vendored UI-kit bodies; a group must keep two product files to count                                                                                                                       |
+| `dead`                                                                                  | zero-reference symbols in framework entry surfaces (route handlers, pages, Trigger.dev task directories from `trigger.config.*`, live barrels) and in generated artifacts (`drizzle-kit pull` dumps, migration snapshots, codegen output)                                         |
+| `dead`                                                                                  | exports of source files a root configuration names by path (`next.config.js` `images.loaderFile`, `package.json` scripts)                                                                                                                                                         |
+| `twin-drift`                                                                            | route-file convention names (`handler`, `handleGet`, `*Page`, `generateMetadata`) inside framework entry files                                                                                                                                                                    |
+| `twin-drift`                                                                            | CRUD and lifecycle method names (`create`, `delete`, `getById`, `shutdown`, ...) declared directly on unrelated classes; free functions with those names keep the ordinary rules                                                                                                  |
+| `twin-drift`                                                                            | a member that calls its same-name counterpart, directly or under an import alias (an operations function over its use-case, a component over the function it renders): a layer, not a parallel implementation                                                                     |
+| `twin-drift`                                                                            | a thin forwarder whose single call is named differently from itself (a web API client, a vendor adapter) is a stub over its peer's concept; overrides of one abstract member; key-qualified lookup members (`getBySlug`, `findByEmail`) on unrelated classes                      |
+| `passthrough-candidates`                                                                | a file with three or more methods forwarding to the same collaborator is a facade; its forwards become boundary signals instead of direct inline advice                                                                                                                           |
+| `wrapper-candidates`, `passthrough-candidates`                                          | boundary terms are read from leaf names, and a term both sides carry (`toBaseRate` forwarding to `parseBaseRate`; a wrapper and its caller both under `lib/auth/`) is shared vocabulary, not a boundary; only asymmetric terms demote a finding to signal tier                    |
+| `passthrough-candidates`                                                                | a class whose methods forward to members of three or more collaborators is a composed-service facade; a curried handler (`return jsonHandler(async () => {...})(req, res, next)`) is not a literal forward                                                                        |
+| `wrapper-candidates`                                                                    | a forward through a module-private variable (`return loadedLanguages.has(lang)`) is a boundary signal because inlining would export the state                                                                                                                                     |
+| `co-change` (hidden coupling)                                                           | documentation that changes alongside the code it describes (`doc-drift` owns stale docs); generated artifacts such as migration journals, snapshots, and codegen output                                                                                                           |
+| `co-change`                                                                             | pairs whose shared commits were only broad sweeps, stale pairs with at most two focused co-changes, and configuration or schema partners (signal tier; listed by co-change)                                                                                                       |
+| `co-change`                                                                             | a `<Name>.script.ts` companion is a component script block, not a maintenance script: a view script changing with its model is model-view coupling                                                                                                                                |
+| `similar`                                                                               | two functions in one file sharing four or more callees at similarity 0.5 or more are direct whatever the vocabulary class; a cross-file pair whose shared evidence mixes domain behavior with scaffolding is direct from similarity 0.6; other scaffolding-only pairs stay signal |
+| `cycles` (health axis)                                                                  | components that cycle through type or symbol references but not through imports; health counts import cycles and lists the rest as a disclosure, while the `cycles` command keeps its symbol-reference default and names the basis                                                |
+| `complexity-hotspots` (extreme count)                                                   | callables above the extreme score only through fan-in, with fewer than 10 branches                                                                                                                                                                                                |
+| `extract-candidates`                                                                    | regions whose extraction would take more than five locals in or hand more than two back (support tier: wide interface); only regions with a narrow or unknown interface count                                                                                                     |
+| `extract-candidates`                                                                    | a selected region that is one statement (an awaited call with callback arguments, a resource or form declaration, a nested function) is support tier: extracting it would only wrap that statement; loop and branch bodies and rendered element subtrees keep their tier           |