scip-query 0.14.0 → 0.16.0

package/docs/analyzer-inventory.md

@@ -20,7 +20,7 @@ The action tiers are:
 
 ## Current Surfaces
 
-The published query surface and private query-helper manifest live in `src/queries/public-query-entries.ts`. The CLI command order and families live in `src/runtime/commands/query-command-specs.ts`. The composite health score runs the phases listed in `HEALTH_PHASES` in `src/queries/health/health.ts`. The diff gate runs the default diff-scoped checks listed in `DIFF_GATE_CHECKS` in `src/queries/impact/diff-gate.ts`; the baseline policy helper remains private to the query tree and runs only for the explicit full health-baseline ratchet. The `tla` command is also ordered in that command registry as an on-demand formal-model verifier, not as a health-scored analyzer.
+The published query surface and private query-helper manifest live in `src/queries/public-query-entries.ts`. The CLI command order and families live in `src/runtime/commands/query-command-specs.ts`. The composite health score runs the phases listed in `HEALTH_PHASES` in `src/queries/health/health.ts`; that health path also carries the full-vs-bounded semantic enrichment budget used by semantic-capable detectors. The diff gate runs the default diff-scoped checks listed in `DIFF_GATE_CHECKS` in `src/queries/impact/diff-gate.ts`; the baseline policy helper remains private to the query tree and runs only for the explicit full health-baseline ratchet. The `tla` command is also ordered in that command registry as an on-demand formal-model verifier, not as a health-scored analyzer.
 
 An earlier `health --json` run on this repository reported:
 
@@ -34,28 +34,28 @@ The declared-coupling config has been refreshed after the inventory surfaced old
 
 ## Health-Scored Analyzers
 
-| Analyzer                         | Evidence examined                                                                                                                                                                                                   |                 Current health role | Recommended action tier                                                                              | Evaluation                                                                                                                                                                                                                                                                                                      |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------: | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `dead`                           | Production definitions, SCIP/source/caller references, package roots, framework-discovered route/page roots, and entry exclusions                                                                                   |                Risk, graph findings | Direct repair for `dead-code`; contextual for `file-internal`                                        | Strong when `kind === dead-code`: zero references and excluded external-live surfaces make deletion likely. `file-internal` is not direct deletion evidence; it may be private helper ownership.                                                                                                                |
-| `cleanup-plan`                   | `dead --only-dead` seed plus conservative cascade references                                                                                                                                                        | Standalone, not direct health phase | Direct repair                                                                                        | Strongest deletion analyzer. It computes ordered batches and can be compiler-verified from the command layer.                                                                                                                                                                                                   |
-| `isolated`                       | Production callables with no callers and no non-self callees                                                                                                                                                        |                Risk, graph findings | Direct repair                                                                                        | Strong dead-leaf signal. It is stricter than `dead` and usually means remove or wire up.                                                                                                                                                                                                                        |
-| `cycles`                         | File dependency graph, with module-hierarchy/test/barrel/entry cycle classification                                                                                                                                 |                                Risk | Direct repair for `real`; support/noise for `module-hierarchy`                                       | Good split already exists. Real cycles normally need architectural repair. Module-hierarchy cycles should not score.                                                                                                                                                                                            |
-| `similar` / `similarAll`         | Callable callee fingerprints, IDF weighting, source-token fallback                                                                                                                                                  |                             Hygiene | Contextual signal                                                                                    | Similarity is a reuse lead, not proof of duplicate semantics. Needs naming, behavior, signatures, and product intent before action. Shared evidence is now labeled as domain, access/query, framework/generic, mixed, or neutral structural overlap.                                                            |
-| `recent-duplicates`              | `similarAll`, React/Vue duplicate analyzers, git file-age orientation                                                                                                                                               |                  Standalone cleanup | Direct repair for `echo`; contextual for `twin`                                                      | Directionality makes this much stronger than plain similarity. A recent echo usually should reuse/delete. Twins still need choice of owner.                                                                                                                                                                     |
-| `react-component-duplicates`     | JSX structure tokens from React profiles                                                                                                                                                                            |                             Hygiene | Contextual signal                                                                                    | Good UI reuse lead. Needs product semantics and design-system judgment before extracting.                                                                                                                                                                                                                       |
-| `react-hook-candidates`          | Shared React hook/state/effect/request/handler tokens, evidence class, action tier, and recommendation                                                                                                              | Hygiene, with `scoreCount` discount | Contextual signal for domain or mixed behavior; support for generic workflow/shared abstraction rows | Better than raw similarity because behavior tokens are named. The output now separates generic UI workflow and existing shared abstractions from domain behavior, but extraction still needs product judgment.                                                                                                  |
-| `react-large-component-pressure` | Component LOC, file LOC, JSX token count, behavior token count, pressure kind, context, recommendation kind                                                                                                         |                             Hygiene | Direct repair pressure with review direction                                                         | Large component pressure usually implies splitting. It now distinguishes JSX, behavior, file, and route/page pressure, but still does not choose the destination directory for extracted code.                                                                                                                  |
-| `vue-component-duplicates`       | Vue template structure tokens                                                                                                                                                                                       |                             Hygiene | Contextual signal                                                                                    | Same reuse caveat as React component duplicates.                                                                                                                                                                                                                                                                |
-| `vue-composable-candidates`      | Vue composable/store/reactivity/lifecycle/request/function/template tokens, evidence class, action tier, and recommendation                                                                                         | Hygiene, with `scoreCount` discount | Contextual signal for domain or mixed behavior; support for generic workflow/shared abstraction rows | Good extraction lead when domain behavior is present. Generic workflow scaffolding remains visible as support, and extraction still needs domain and locality judgment.                                                                                                                                         |
-| `vue-large-view-pressure`        | SFC total/template/script/style/external-script line counts, pressure kind, context, recommendation kind                                                                                                            |                             Hygiene | Direct repair pressure with review direction                                                         | Usually implies splitting a large view. It now distinguishes template, script, style, external-script, and route/page pressure, but still needs companion directory-locality guidance.                                                                                                                          |
-| `extract-candidates`             | Large callable callee clusters, co-occurrence isolation, extraction kind, action tier, and recommendation                                                                                                           |                             Hygiene | Contextual signal                                                                                    | It finds possible extraction seams, not proof of a new abstraction. The output now distinguishes workflow orchestration from broad/cohesive helper clusters and keeps every row as signal.                                                                                                                      |
-| `wrapper-candidates`             | Small production callables with one real external caller, caller fan-in, and boundary-token evidence                                                                                                                |                             Hygiene | Contextual signal, sometimes direct                                                                  | Single-caller wrappers can be needless indirection, but may also be names, domain/lifecycle boundaries, test seams, or API shaping. Boundary evidence discounts those without hiding them.                                                                                                                      |
-| `passthrough-candidates`         | Small production callables with exactly one callee, literal pass-through body, runtime-boundary evidence, public-facade evidence, action tier, recommendation, and score count                                      | Hygiene, with `scoreCount` discount | Direct when no boundary or public-facade evidence is present; contextual signal when either exists   | Body-shape gate is real. Boundary evidence distinguishes adapter, provider, public, capability, transport, lifecycle, access-policy, and facade-shaped forwarders; public-facade evidence separately identifies package-public or rooted exported passthroughs.                                                 |
-| `stale-abstractions`             | Type-like definitions, real consumers, barrel consumers, transitive reachability, definer usage, confidence, staleness kind, action tier, and recommendation                                                        |                             Hygiene | Direct for unused abstractions; contextual signal for one-consumer ownership rows                    | `0 consumers` is direct repair. `1 consumer` is contextual, including high-confidence misplaced types, because the repair may be move, inline, keep, or document as public contract.                                                                                                                            |
-| `drift`                          | File dep graph, symbol ref graph, semantic/source import usage, explicit or inferred layer policy, sibling patterns, action tier, policy basis, recommendation                                                      |                             Hygiene | Split by kind                                                                                        | `unused-import` is direct repair. Explicit `layer-violation` is direct; inferred layer policy and `pattern-deviation` rows are contextual signal. Pattern deviations remain excluded from health scoring.                                                                                                       |
-| `complexity-hotspots`            | Production callable LOC, fan-in, fan-out, callee count                                                                                                                                                              |                                Risk | Direct repair pressure                                                                               | Complexity pressure usually means refactor, but the current score is structural, not cyclomatic. It should be separate from branch-count complexity.                                                                                                                                                            |
-| `co-change` / hidden coupling    | Git co-change pairs, dependency edges, declared couplings, file noise filters, partner-class labels, declared-coupling suggestions, commit scope, recency context, commit-subject context, and score-weighted count |  Risk, weighted by history strength | Contextual signal                                                                                    | Strong evidence that coordination may be missing, but not proof that extraction or unification is correct. Partner classes, history context, subject context, and score weighting now separate contract-like focused current pairs from broad, stale, or unlabeled history before suggesting declared coupling. |
-| Suppression inventory            | `scip-query: ignore-*` comments in source, plus structured `.scipquery.json` suppressions                                                                                                                           |               Evidence quality axis | Meta signal                                                                                          | Useful precision feedback. High suppressions should reduce trust or weight for that detector family. Structured file-scoped suppressions now validate path freshness.                                                                                                                                           |
+| Analyzer                         | Evidence examined                                                                                                                                                                                                                   |                 Current health role | Recommended action tier                                                                                      | Evaluation                                                                                                                                                                                                                                                                                                               |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------: | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `dead`                           | Production definitions, SCIP/source/caller references including tests, transitive declared package/Cargo library surfaces, framework entry files, interface/protocol contracts, implicit runtime reachability, and configured roots |                Risk, graph findings | Direct repair for certified TypeScript `dead-code`; contextual for `file-internal` and Rust `implicit-usage` | TypeScript `dead-code` is certified under the repository-dead truth rule. Rust public library items are rooted and implicit runtime reachability is a non-scoring signal, but Rust `dead-code` remains insufficiently evidenced after a three-repository replay. Checker verification is still required before deletion. |
+| `cleanup-plan`                   | `dead --only-dead` seed plus conservative cascade references                                                                                                                                                                        | Standalone, not direct health phase | Direct repair                                                                                                | Strongest deletion analyzer. It computes ordered batches and can be compiler-verified from the command layer.                                                                                                                                                                                                            |
+| `isolated`                       | Production callables with no callers and no non-self callees                                                                                                                                                                        |                Risk, graph findings | Direct repair                                                                                                | Strong dead-leaf signal. It is stricter than `dead` and usually means remove or wire up.                                                                                                                                                                                                                                 |
+| `cycles`                         | File dependency graph, with module-hierarchy/test/barrel/entry cycle classification                                                                                                                                                 |                                Risk | Direct repair for `real`; support/noise for `module-hierarchy`                                               | Good split already exists. Real cycles normally need architectural repair. Module-hierarchy cycles should not score.                                                                                                                                                                                                     |
+| `similar` / `similarAll`         | Callable callee fingerprints, IDF weighting, source-token fallback                                                                                                                                                                  |                             Hygiene | Contextual signal                                                                                            | Similarity is a reuse lead, not proof of duplicate semantics. Needs naming, behavior, signatures, and product intent before action. Shared evidence is now labeled as domain, access/query, framework/generic, mixed, or neutral structural overlap.                                                                     |
+| `recent-duplicates`              | `similarAll`, React/Vue duplicate analyzers, git file-age orientation                                                                                                                                                               |                  Standalone cleanup | Direct repair for `echo`; contextual for `twin`                                                              | Directionality makes this much stronger than plain similarity. A recent echo usually should reuse/delete. Twins still need choice of owner.                                                                                                                                                                              |
+| `react-component-duplicates`     | JSX structure tokens from React profiles                                                                                                                                                                                            |                             Hygiene | Contextual signal                                                                                            | Good UI reuse lead. Needs product semantics and design-system judgment before extracting.                                                                                                                                                                                                                                |
+| `react-hook-candidates`          | Shared React hook/state/effect/request/handler tokens, evidence class, action tier, and recommendation                                                                                                                              | Hygiene, with `scoreCount` discount | Contextual signal for domain or mixed behavior; support for generic workflow/shared abstraction rows         | Better than raw similarity because behavior tokens are named. The output now separates generic UI workflow and existing shared abstractions from domain behavior, but extraction still needs product judgment.                                                                                                           |
+| `react-large-component-pressure` | Component LOC, file LOC, JSX token count, behavior token count, pressure kind, context, recommendation kind                                                                                                                         |                             Hygiene | Direct repair pressure with review direction                                                                 | Large component pressure usually implies splitting. It now distinguishes JSX, behavior, file, and route/page pressure, but still does not choose the destination directory for extracted code.                                                                                                                           |
+| `vue-component-duplicates`       | Vue template structure tokens                                                                                                                                                                                                       |                             Hygiene | Contextual signal                                                                                            | Same reuse caveat as React component duplicates.                                                                                                                                                                                                                                                                         |
+| `vue-composable-candidates`      | Vue composable/store/reactivity/lifecycle/request/function/template tokens, evidence class, action tier, and recommendation                                                                                                         | Hygiene, with `scoreCount` discount | Contextual signal for domain or mixed behavior; support for generic workflow/shared abstraction rows         | Good extraction lead when domain behavior is present. Generic workflow scaffolding remains visible as support, and extraction still needs domain and locality judgment.                                                                                                                                                  |
+| `vue-large-view-pressure`        | SFC total/template/script/style/external-script line counts, pressure kind, context, recommendation kind                                                                                                                            |                             Hygiene | Direct repair pressure with review direction                                                                 | Usually implies splitting a large view. It now distinguishes template, script, style, external-script, and route/page pressure, but still needs companion directory-locality guidance.                                                                                                                                   |
+| `extract-candidates`             | Large callable callee clusters, co-occurrence isolation, extraction kind, action tier, and recommendation                                                                                                                           |                             Hygiene | Contextual signal                                                                                            | It finds possible extraction seams, not proof of a new abstraction. The output now distinguishes workflow orchestration from broad/cohesive helper clusters and keeps every row as signal.                                                                                                                               |
+| `wrapper-candidates`             | Small production callables with one real external caller, caller fan-in, and boundary-token evidence                                                                                                                                |                             Hygiene | Contextual signal, sometimes direct                                                                          | Single-caller wrappers can be needless indirection, but may also be names, domain/lifecycle boundaries, test seams, or API shaping. Boundary evidence discounts those without hiding them.                                                                                                                               |
+| `passthrough-candidates`         | Small production callables with exactly one callee, literal pass-through body, runtime-boundary evidence, public-facade evidence, action tier, recommendation, and score count                                                      | Hygiene, with `scoreCount` discount | Direct when no boundary or public-facade evidence is present; contextual signal when either exists           | Body-shape gate is real. Boundary evidence distinguishes adapter, provider, public, capability, transport, lifecycle, access-policy, and facade-shaped forwarders; public-facade evidence separately identifies package-public or rooted exported passthroughs.                                                          |
+| `stale-abstractions`             | Type-like definitions, real consumers, barrel consumers, transitive reachability, definer usage, confidence, staleness kind, action tier, and recommendation                                                                        |                             Hygiene | Direct for unused abstractions; contextual signal for one-consumer ownership rows                            | `0 consumers` is direct repair. `1 consumer` is contextual, including high-confidence misplaced types, because the repair may be move, inline, keep, or document as public contract.                                                                                                                                     |
+| `drift`                          | File dep graph, symbol ref graph, semantic/source import usage, explicit or inferred layer policy, sibling patterns, action tier, policy basis, recommendation                                                                      |                             Hygiene | Split by kind                                                                                                | `unused-import` is direct repair. Explicit `layer-violation` is direct; inferred layer policy and `pattern-deviation` rows are contextual signal. Pattern deviations remain excluded from health scoring.                                                                                                                |
+| `complexity-hotspots`            | Production callable LOC, fan-in, fan-out, callee count                                                                                                                                                                              |                                Risk | Direct repair pressure                                                                                       | Complexity pressure usually means refactor, but the current score is structural, not cyclomatic. It should be separate from branch-count complexity.                                                                                                                                                                     |
+| `co-change` / hidden coupling    | Git co-change pairs, dependency edges, declared couplings, file noise filters, partner-class labels, declared-coupling suggestions, commit scope, recency context, commit-subject context, and score-weighted count                 |  Risk, weighted by history strength | Contextual signal                                                                                            | Strong evidence that coordination may be missing, but not proof that extraction or unification is correct. Partner classes, history context, subject context, and score weighting now separate contract-like focused current pairs from broad, stale, or unlabeled history before suggesting declared coupling.          |
+| Suppression inventory            | `scip-query: ignore-*` comments in source, plus structured `.scipquery.json` suppressions                                                                                                                                           |               Evidence quality axis | Meta signal                                                                                                  | Useful precision feedback. High suppressions should reduce trust or weight for that detector family. Structured file-scoped suppressions now validate path freshness.                                                                                                                                                    |
 
 ## Diff-Gate Checks
 
@@ -254,3 +254,11 @@ wiring decisions (test-quality's health eligibility is ledgered as a
 followup). Registration files (`queryCommandOrder`,
 `PUBLIC_QUERY_ENTRIES`, `query-command-specs.ts`) still own their
 canonical lists; only the list contents grew.
+
+## 2026-07-08 Rust Semantic Parity Follow-Up
+
+The `src/queries/health/health.ts` citation remains accurate after the Rust
+semantic parity slice. Health still owns the composite phase inventory and
+score model, and it now threads semantic enrichment through the health budget:
+full/default health enables semantic facts, while bounded large-index health
+can explicitly disable them.

package/docs/analyzer-validation-ledger.md

@@ -12,12 +12,12 @@ The companion documents are:
 
 The ledger is anchored to the current tool surface, not memory.
 
-| Surface                   | Source                                                                                                                                                                                                                                                                                                       | Why it anchors the ledger                                                                     |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
-| Repo-wide health analysis | `scip-query code health --json` reported `src/queries/health/health.ts:217`, where `health()` runs `runHealthAnalyses()` and `buildHealthReport()`.                                                                                                                                                          | Every repo-wide analyzer validation must eventually reconcile with health output and scoring. |
+| Surface                   | Source                                                                                                                                                                                                                                                                                                        | Why it anchors the ledger                                                                     |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Repo-wide health analysis | `scip-query code health --json` reported `src/queries/health/health.ts:218`, where `health()` runs `runHealthAnalyses()` and `buildHealthReport()` through the health budget that carries full-vs-bounded semantic enrichment.                                                                                | Every repo-wide analyzer validation must eventually reconcile with health output and scoring. |
 | Change-time gate analysis | `scip-query code diffGate --json` reported `src/queries/impact/diff-gate.ts:228`, where `diffGate()` runs the default diff-scoped checks: `echo`, `incomplete-migration`, `co-change-partner`, `doc-reference`, `unused-params`, and `new-dead`. The baseline ratchet is explicit because it is repo-wide.    | Every diff-only analyzer needs a separate validation path from repo-wide health.              |
-| Public command registry   | `scip-query trace queryCommandOrder --json` reported `src/runtime/commands/query-command-specs.ts:11`, where the public query command order starts. `scip-query code queryCommandDescriptor --json` reported `src/runtime/commands/query-command-specs.ts:104`, where command descriptors are resolved by id. | The ledger must not silently miss a public analyzer command.                                 |
-| Diff-gate check list      | `scip-query trace DIFF_GATE_CHECKS --json` reported `src/queries/impact/diff-gate.ts:64`, where the canonical diff-gate check list is exported.                                                                                                                                                              | The ledger must cover every change-time check that can block a diff.                          |
+| Public command registry   | `scip-query trace queryCommandOrder --json` reported `src/runtime/commands/query-command-specs.ts:11`, where the public query command order starts. `scip-query code queryCommandDescriptor --json` reported `src/runtime/commands/query-command-specs.ts:104`, where command descriptors are resolved by id. | The ledger must not silently miss a public analyzer command.                                  |
+| Diff-gate check list      | `scip-query trace DIFF_GATE_CHECKS --json` reported `src/queries/impact/diff-gate.ts:64`, where the canonical diff-gate check list is exported.                                                                                                                                                               | The ledger must cover every change-time check that can block a diff.                          |
 
 ## Core Concepts
 
@@ -45,22 +45,24 @@ A repair outcome is the result of acting on an analyzer finding. It matters beca
 
 Closeout status: all active ledger rows are complete as of 2026-06-22. Remaining future work is provider- or corpus-gated, not an unfinished validation slice: true co-change issue/PR label ingestion needs a repository metadata provider, and locality score integration needs stronger consumer-coverage plus repair-outcome evidence.
 
-| ID      | Item                                   | Scope                                                                                                                                                                                  | Status     | Next action                                                                               | Done signal                                                                                              |
-| ------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| AVL-001 | Field evaluation baseline              | Run the protocol on `scip-query`, `Stable_Management`, `Vega_2.0`, and `SynthRunnerRust`.                                                                                              | `complete` | Completed in `docs/validation/2026-06-21-second-repo-confirmation.md`.                    | A dated run summary exists for each repo with raw-output locations and sampling notes.                   |
-| AVL-002 | Direct repair analyzer verdicts        | `cleanup-plan`, `dead`, `new-dead`, `isolated`, `unused-params`, `unused-imports`, `redundant-reexports`, `passthrough-candidates`, `cycles`, broken `doc-drift`, and `doc-reference`. | `complete` | Completed in `docs/validation/2026-06-21-direct-deletion-family-closure-result.md`.       | Each direct analyzer has TP/FP/FN counts, accepted-design examples, and precision actions.               |
-| AVL-003 | Contextual signal analyzer verdicts    | Similarity, extraction, locality, wrapper, stale abstraction, frontend duplicate, hook/composable, co-change, bottleneck, coupling, drift, and deep-chain families.                    | `complete` | Completed in `docs/validation/2026-06-21-contextual-signal-closure-result.md`.            | Each contextual family has a reviewed precision note and a score-weight recommendation.                  |
-| AVL-004 | Support analysis accuracy              | `affected`, `change-surface`, `plan-context`, navigation commands, graph metrics, and `self-audit`.                                                                                    | `complete` | Completed in `docs/validation/2026-06-21-support-analysis-accuracy-result.md`.            | Support commands have referential-accuracy notes and known unsupported cases.                            |
-| AVL-005 | Analyzer implementation parity         | Confirm each public analyzer command's documented behavior matches implementation behavior.                                                                                            | `complete` | Completed in `docs/validation/2026-06-21-analyzer-implementation-parity-result.md`.       | The inventory and protocol either match implementation or list required doc/code corrections.            |
-| AVL-006 | Score calibration                      | Evaluate direct findings, contextual signals, suppressions, validation ratio, and signal backlog pressure.                                                                             | `complete` | Completed in `docs/validation/2026-06-21-score-calibration-finalization-result.md`.       | A calibration memo states score-weight changes, accepted current weights, or blocked evidence gaps.      |
-| AVL-007 | Output and schema quality              | Verify each analyzer emits enough structured evidence for users and agents to review the claim.                                                                                        | `complete` | Completed in `docs/validation/2026-06-21-output-schema-quality-finalization-result.md`.   | Each analyzer family has an output-quality verdict and missing-field list.                               |
-| AVL-008 | Performance and budget behavior        | Check large-index behavior, `--full`, scan limits, git-history bounds, and graceful degradation.                                                                                       | `complete` | Completed in `docs/validation/2026-06-21-performance-budget-behavior-result.md`.          | Budget behavior is documented with any timeout, cap, or misleading-empty-output issues.                  |
-| AVL-009 | Suppression lifecycle                  | Evaluate whether suppressions are stale, justified, expired, or useful as detector precision feedback.                                                                                 | `complete` | Completed in `docs/validation/2026-06-21-suppression-lifecycle-result.md`.                | Suppression categories have counts, stale examples, and trust-weight recommendations.                    |
-| AVL-010 | Cross-language capability boundaries   | Establish what works for TypeScript, React, Vue, Rust, and any unsupported language surfaces.                                                                                          | `complete` | Completed in `docs/validation/2026-06-21-cross-language-capability-boundaries-result.md`. | Capability notes distinguish "no findings" from "not supported by current evidence."                     |
-| AVL-011 | Agent repair outcomes                  | Test whether acting on analyzer findings produces better code rather than churn or misplaced abstraction.                                                                              | `complete` | Completed in `docs/validation/2026-06-21-agent-repair-outcomes-result.md`.                | Each action tier has at least one reviewed repair outcome or an explicit reason it cannot be tested yet. |
-| AVL-012 | Locality analyzer validation           | Validate the proposed `locality-candidates` report and `scip-locality-review` skill workflow before implementation.                                                                    | `complete` | Completed in `docs/validation/2026-06-21-locality-analyzer-validation-result.md`.         | The locality design has TP/FP/FN-style examples and a go/no-go recommendation for implementation.        |
-| AVL-013 | Config and declared-coupling freshness | Check whether `.scipquery.json` declared couplings and suppressions still point at current paths.                                                                                      | `complete` | Completed in `docs/validation/2026-06-21-config-declared-coupling-freshness-result.md`.   | Stale config paths are fixed, removed, or documented as intentionally retained.                          |
-| AVL-014 | Public command surface coverage        | Ensure every public analyzer command is present in the inventory, protocol, and ledger.                                                                                                | `complete` | Completed in `docs/validation/2026-06-21-public-command-surface-coverage-result.md`.      | A coverage checklist shows no missing analyzer or marks non-analyzer support commands separately.        |
+| ID      | Item                                   | Scope                                                                                                                                                                                  | Status     | Next action                                                                                                                         | Done signal                                                                                                                            |
+| ------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| AVL-001 | Field evaluation baseline              | Run the protocol on `scip-query`, `Stable_Management`, `Vega_2.0`, and `SynthRunnerRust`.                                                                                              | `complete` | Completed in `docs/validation/2026-06-21-second-repo-confirmation.md`.                                                              | A dated run summary exists for each repo with raw-output locations and sampling notes.                                                 |
+| AVL-002 | Direct repair analyzer verdicts        | `cleanup-plan`, `dead`, `new-dead`, `isolated`, `unused-params`, `unused-imports`, `redundant-reexports`, `passthrough-candidates`, `cycles`, broken `doc-drift`, and `doc-reference`. | `complete` | Completed in `docs/validation/2026-06-21-direct-deletion-family-closure-result.md`.                                                 | Each direct analyzer has TP/FP/FN counts, accepted-design examples, and precision actions.                                             |
+| AVL-003 | Contextual signal analyzer verdicts    | Similarity, extraction, locality, wrapper, stale abstraction, frontend duplicate, hook/composable, co-change, bottleneck, coupling, drift, and deep-chain families.                    | `complete` | Completed in `docs/validation/2026-06-21-contextual-signal-closure-result.md`.                                                      | Each contextual family has a reviewed precision note and a score-weight recommendation.                                                |
+| AVL-004 | Support analysis accuracy              | `affected`, `change-surface`, `plan-context`, navigation commands, graph metrics, and `self-audit`.                                                                                    | `complete` | Completed in `docs/validation/2026-06-21-support-analysis-accuracy-result.md`.                                                      | Support commands have referential-accuracy notes and known unsupported cases.                                                          |
+| AVL-005 | Analyzer implementation parity         | Confirm each public analyzer command's documented behavior matches implementation behavior.                                                                                            | `complete` | Completed in `docs/validation/2026-06-21-analyzer-implementation-parity-result.md`.                                                 | The inventory and protocol either match implementation or list required doc/code corrections.                                          |
+| AVL-006 | Score calibration                      | Evaluate direct findings, contextual signals, suppressions, validation ratio, and signal backlog pressure.                                                                             | `complete` | Completed in `docs/validation/2026-06-21-score-calibration-finalization-result.md`.                                                 | A calibration memo states score-weight changes, accepted current weights, or blocked evidence gaps.                                    |
+| AVL-007 | Output and schema quality              | Verify each analyzer emits enough structured evidence for users and agents to review the claim.                                                                                        | `complete` | Completed in `docs/validation/2026-06-21-output-schema-quality-finalization-result.md`.                                             | Each analyzer family has an output-quality verdict and missing-field list.                                                             |
+| AVL-008 | Performance and budget behavior        | Check large-index behavior, `--full`, scan limits, git-history bounds, and graceful degradation.                                                                                       | `complete` | Completed in `docs/validation/2026-06-21-performance-budget-behavior-result.md`.                                                    | Budget behavior is documented with any timeout, cap, or misleading-empty-output issues.                                                |
+| AVL-009 | Suppression lifecycle                  | Evaluate whether suppressions are stale, justified, expired, or useful as detector precision feedback.                                                                                 | `complete` | Completed in `docs/validation/2026-06-21-suppression-lifecycle-result.md`.                                                          | Suppression categories have counts, stale examples, and trust-weight recommendations.                                                  |
+| AVL-010 | Cross-language capability boundaries   | Establish what works for TypeScript, React, Vue, Rust, and any unsupported language surfaces.                                                                                          | `complete` | Completed in `docs/validation/2026-06-21-cross-language-capability-boundaries-result.md`.                                           | Capability notes distinguish "no findings" from "not supported by current evidence."                                                   |
+| AVL-011 | Agent repair outcomes                  | Test whether acting on analyzer findings produces better code rather than churn or misplaced abstraction.                                                                              | `complete` | Completed in `docs/validation/2026-06-21-agent-repair-outcomes-result.md`.                                                          | Each action tier has at least one reviewed repair outcome or an explicit reason it cannot be tested yet.                               |
+| AVL-012 | Locality analyzer validation           | Validate the proposed `locality-candidates` report and `scip-locality-review` skill workflow before implementation.                                                                    | `complete` | Completed in `docs/validation/2026-06-21-locality-analyzer-validation-result.md`.                                                   | The locality design has TP/FP/FN-style examples and a go/no-go recommendation for implementation.                                      |
+| AVL-013 | Config and declared-coupling freshness | Check whether `.scipquery.json` declared couplings and suppressions still point at current paths.                                                                                      | `complete` | Completed in `docs/validation/2026-06-21-config-declared-coupling-freshness-result.md`.                                             | Stale config paths are fixed, removed, or documented as intentionally retained.                                                        |
+| AVL-014 | Public command surface coverage        | Ensure every public analyzer command is present in the inventory, protocol, and ledger.                                                                                                | `complete` | Completed in `docs/validation/2026-06-21-public-command-surface-coverage-result.md`.                                                | A coverage checklist shows no missing analyzer or marks non-analyzer support commands separately.                                      |
+| AVL-015 | TypeScript `dead` certification        | Fixed-seed four-repository precision review, causal remediation, holdout replay, and known-positive recall.                                                                            | `complete` | Certified in `docs/validation/2026-07-10-typescript-dead-certification.md`.                                                         | Precision, confidence, corpus, and recall gates pass under the repository-dead truth rule.                                             |
+| AVL-016 | Rust `dead` hardening                  | Pinned Codex, SynthRunnerRust, and VegaAssistant review covering Cargo surfaces, traits, macros, reflection, examples, and positive recall.                                            | `complete` | Hardened but insufficiently evidenced in `docs/validation/2026-07-10-rust-dead-certification.md`; expand the corpus before renewal. | Every baseline false positive is removed, applicability is visible, recall fixtures pass, and failed certification gates are explicit. |
 
 ## Public Command Coverage Checklist
 
@@ -324,6 +326,15 @@ and a `detectorPrecision` field (per-check finding-outcome stats from the new
 finding-outcome ledger) — both paths still compute and render through the same
 command surfaces cited above.
 
+## 2026-07-08 Rust Semantic Parity Follow-Up
+
+The `src/queries/health/health.ts` citation remains accurate after the Rust
+semantic parity slice. Health still owns the composite phase inventory and
+score assembly; the health budget now also carries whether a run should enrich
+detectors with semantic facts. Full/default health keeps semantic enrichment
+enabled, while bounded large-index health records the explicit semantic-off
+budget choice.
+
 ## 2026-07-02 Doc-Reference Hub-Cascade Follow-Up
 
 The `diffGate()` and `DIFF_GATE_CHECKS` citations were refreshed (line anchors
@@ -334,3 +345,22 @@ one clustered finding carrying `citationCount`, up to 3 `citationExemplars`,
 and an explicit `suppressedCount`. Default diff-gate still runs the same
 check family through the same entry point; per-doc findings under the
 threshold are unchanged.
+
+## 2026-07-10 TypeScript Dead-Code Certification Follow-Up
+
+The direct-repair `dead` row now has a detector-language certificate rather
+than relying on the earlier mixed-family calibration. The pinned four-repo
+baseline produced 25 valid and 53 invalid TypeScript findings. Shared fixes
+made test references count as repository usage, propagated declared package
+surfaces through re-exports, recognized framework entry files, and excluded
+interface, constructor, React lifecycle, and implemented-protocol contracts.
+
+The final fixed-seed review contained 43 valid findings and zero invalid
+findings across Vega_2.0, openwork, Stable_Management, and traceroot. Observed
+precision was 100%, the 95% Wilson lower bound was 91.8%, and three positive
+fixtures continued to detect ordinary unreferenced definitions. The retained
+claim is narrowly scoped: TypeScript `dead-code` rows are certified
+repository-dead candidates, while `file-internal`, other detector families,
+Rust, Python, and the aggregate health score retain independent status. The
+full evidence is in
+`docs/validation/2026-07-10-typescript-dead-certification.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scip-query",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Evidence and verification for AI coding agents: map code, reuse concepts, finish migrations, and gate diffs.",
   "type": "module",
   "main": "dist/index.js",
@@ -317,6 +317,7 @@
     "lint": "npm run format:check && eslint src tests tsup.config.ts && node scripts/check-skill-links.mjs",
     "build:scip-windows": "node scripts/build-scip-windows.mjs",
     "bench:evidence-products": "node scripts/evidence-product-contract.mjs",
+    "bench:native-symbol-leaf": "node scripts/bench-native-symbol-leaf.mjs",
     "calibrate": "node scripts/accuracy-calibration.mjs",
     "docs:commands": "vite-node scripts/render-command-reference.ts --write",
     "prepublishOnly": "npm run publish:scip-windows && npm run build",

package/scripts/build-scip-windows.mjs

@@ -45,16 +45,16 @@ try {
   writeFileSync(
     join(VENDOR_DIR, 'README.md'),
     [
-      '# scip.exe release assets',
+      '# Windows scip.exe npm sidecar',
       '',
       `These binaries are built from ${SCIP_REPO_URL} at ${SCIP_VERSION}.`,
-      'They are NOT bundled into the npm package. Upload each as a GitHub release',
-      'asset (scip-win32-<arch>.exe) and pin url + sha256 in',
-      'src/runtime/scip-windows-assets.ts before publishing — scip-query downloads',
-      'and checksum-verifies them on demand so Windows `reindex` works without',
-      'requiring Go or WSL.',
+      'They are bundled in the OS-gated `scip-query-scip-windows` npm package. The main',
+      '`scip-query` package declares that sidecar as an optional dependency, so npm',
+      'installs it automatically on Windows and `reindex` works without Go or WSL.',
       '',
-      'Run `npm run build:scip-windows` to (re)build these before publishing.',
+      'Run `npm run build:scip-windows` to rebuild the binaries. Publishing the main',
+      'package verifies the version pin, builds missing binaries, and publishes the',
+      'matching sidecar first.',
       '',
     ].join('\n'),
   );

package/skills/_shared/SKILL.md

@@ -91,7 +91,7 @@ scip-query slice <symbol> # Reference-level program slice: what affects this (ba
 ### Cleanup
 
 ```bash
-scip-query dead [scope] # Find dead code and file-internal symbols (no cross-file consumers)
+scip-query dead [scope] # Find repository-dead code, file-internal symbols, and implicit-usage signals
 scip-query unused-imports <file> # Find imports not referenced in the same file
 scip-query isolated # Find completely orphaned symbols (no references at all)
 scip-query similar [symbol] [other] # Find heuristic function similarity candidates from callee fingerprints
@@ -130,12 +130,12 @@ scip-query similar-signatures # Find functions with near-identical type signatur
 
 ```bash
 scip-query hotspots # Most-referenced symbols in the codebase (choke points)
-scip-query fan-in [symbol] # How many files reference a symbol (or top fan-in across codebase)
+scip-query fan-in [symbol] # Count files referencing an exact symbol; top JSON rows include exact symbol identity
 scip-query fan-out [file] # How many external symbols a file uses (or top fan-out across codebase)
 scip-query coupling [file1] [file2] # Coupling between two files, or top coupled pairs in codebase
 scip-query cycles # Detect circular dependency chains between files
 scip-query bottlenecks # Find coupling hubs: high fan-in AND high fan-out
-scip-query deep-chains # Find the longest transitive dependency chains
+scip-query deep-chains # Find the longest condensed dependency-component chains
 scip-query call-graph <symbol> # Show incoming callers and outgoing callees for a symbol
 ```
 
@@ -174,6 +174,7 @@ scip-query complexity <symbol> # Per-symbol complexity: branches, cyclomatic est
 
 ```bash
 scip-query bench # Benchmark indexing and command runtimes for this repository
+scip-query work-audit <profile> # Rank exact repeated computations in a profiling JSONL file by measured avoidable time
 scip-query 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
 scip-query setup-hooks # Install or refresh project-local Codex and Claude Code lifecycle hooks
 scip-query check-deps # Check whether scip-query and the detected language indexers are actually runnable
@@ -181,13 +182,14 @@ scip-query capabilities # Report which evidence and verification capabilities ar
 scip-query capability-matrix # Deprecated alias for capabilities --matrix
 scip-query init # Create a .scipquery.json config file for this project
 scip-query config-validate # Validate .scipquery.json, including structured suppressions and declared coupling groups
-scip-query suppress <id> # Record an accepted finding in .scipquery.json with a required reason
+scip-query suppress <id> # Record an accepted finding as a file under .scipquery/suppressions/ with a required reason
+scip-query effectiveness # Per-check effectiveness from the committed outcome ledger: caught, same-HEAD verified fixes, suppressed, unverified disappearances, and precision
 scip-query doctor # Diagnose config, index freshness, dependency readiness, and project capabilities
-scip-query setup # Bootstrap this project: install agent skills, refresh the index, verify capabilities, and report health
+scip-query setup # Bootstrap this project: enable automatic indexing, install agent skills, refresh the index, verify capabilities, and report health
 scip-query 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
 scip-query setup-ci # Write a GitHub Actions workflow that runs scip-query reindex and diff-gate on pull requests
 scip-query uninstall # Remove scip-query-owned skill links, project hooks, and managed agent setup blocks
-scip-query watch # Watch for file changes in the foreground and reindex automatically
+scip-query watch # Watch in the foreground or manage the per-project background refresh service
 scip-query status # Show index status for this project
 ```
 
@@ -196,7 +198,7 @@ scip-query status # Show index status for this project
 ## Detector Reliability
 
 Calibrated against two external production repos on 2026-07-01
-(docs/validation/2026-07-01-external-calibration-*.md). Weight findings by
+(docs/validation/2026-07-01-external-calibration-\*.md). Weight findings by
 measured precision, not by volume:
 
 - **Strong signal** — `complexity-hotspots` (~90%), `recent-duplicates` (~75%), graph facts (`refs`, `trace`, `deps`), compiler-verified `cleanup-plan --verify`.
@@ -205,6 +207,7 @@ measured precision, not by volume:
 - **Advisory gate findings** (marked `(advisory)`) never block; they are context, not obligations.
 - **False-dead archetypes (2026-07-02 remediation, docs/plans/2026-07-02-followups.md items 1-3)**: `import type`-only consumers (incl. tsconfig `paths`-aliased specifiers) and pnpm/npm/yarn workspace cross-package consumers (incl. unbuilt `dist/` exports maps) are now resolved by the shared reference-counting layer that `dead`/`isolated`/`new-dead`/`stale-abstractions`/`production-callables` all consume; Vue `<script setup>` composable consumers were already correctly resolved (verified live, no code change needed). One narrow residual gap remains: a symbol with an **ambiguous leaf name** (a same-named definition exists elsewhere in the project) reached only through a **re-exporting barrel file** in a workspace package can still misattribute — `new-dead` labels that specific shape `unconfirmed (cross-package ambiguous-name resolution gap)` with `evidence: "heuristic"` and lowered confidence instead of asserting `dead`; treat those as "verify manually," not as a fact. Everything else in this class is a normal graph-fact `dead` claim again — confirm with `refs` when in doubt, same as any other finding.
 - **Ledger nudges**: when `diff-gate --hook` reports "this check is rarely acted on in this repo", either tune that check's config, suppress the standing findings with reasons, or consciously accept the noise — do not let unresolved findings accumulate as wallpaper.
+- **Effectiveness ledger**: every completed diff-gate run, including JSON and hook mode, appends caught/resolved/suppressed transitions to `.scipquery/ledger/events.jsonl` (committed, conflict-free via a scoped `merge=union` gitattribute — commit it with your changes). Query it with `scip-query effectiveness [--since 30d] [--check <check>] [--json]`: per check it reports findings caught, same-HEAD verified fixed, suppressed, still open, `moved` (rename noise), `unverified` (the finding disappeared after HEAD changed or without Git identity), precision (verified fixed ÷ verified fixed plus suppressed), and median days-to-fix. Run diff-gate before and after a repair, before committing, to earn verified credit. Standalone detector commands are not outcome-tracked until they expose complete-scan evidence.
 
 ## Diff Gate Checks
 
@@ -214,17 +217,17 @@ measured precision, not by volume:
 
 Run the rows that match the actual edit:
 
-| Change made | Check |
-| --- | --- |
-| Extracted a helper or abstraction | `scip-query incomplete-migration --json --full` |
-| Added a helper, module, component, hook, composable, or adapter | `scip-query similar <symbol> --json --full` and `scip-query recent-duplicates --json --full` |
-| Added parameters, options, props, config flags, or broad option objects | `scip-query unused-params --json --full` |
-| Added a wrapper, facade, forwarding layer, alias, or re-export | `scip-query wrapper-candidates --json --full`, `scip-query passthrough-candidates --json --full`, and `scip-query redundant-reexports` when exports changed |
-| Added an interface, base class, adapter contract, or type alias | `scip-query stale-abstractions --json --full` |
-| Changed schema, config, generated files, public contracts, command descriptors, or docs-backed behavior | `scip-query co-change <file> --json --full` and `scip-query doc-drift --json --full` |
-| Deleted code | `scip-query cleanup-plan --verify --json` |
-| Changed React components or hooks | the React frontend commands above |
-| Changed Vue SFCs or composables | the Vue frontend commands above |
+| Change made                                                                                             | Check                                                                                                                                                       |
+| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Extracted a helper or abstraction                                                                       | `scip-query incomplete-migration --json --full`                                                                                                             |
+| Added a helper, module, component, hook, composable, or adapter                                         | `scip-query similar <symbol> --json --full` and `scip-query recent-duplicates --json --full`                                                                |
+| Added parameters, options, props, config flags, or broad option objects                                 | `scip-query unused-params --json --full`                                                                                                                    |
+| Added a wrapper, facade, forwarding layer, alias, or re-export                                          | `scip-query wrapper-candidates --json --full`, `scip-query passthrough-candidates --json --full`, and `scip-query redundant-reexports` when exports changed |
+| Added an interface, base class, adapter contract, or type alias                                         | `scip-query stale-abstractions --json --full`                                                                                                               |
+| Changed schema, config, generated files, public contracts, command descriptors, or docs-backed behavior | `scip-query co-change <file> --json --full` and `scip-query doc-drift --json --full`                                                                        |
+| Deleted code                                                                                            | `scip-query cleanup-plan --verify --json`                                                                                                                   |
+| Changed React components or hooks                                                                       | the React frontend commands above                                                                                                                           |
+| Changed Vue SFCs or composables                                                                         | the Vue frontend commands above                                                                                                                             |
 
 Every implemented change ends with:
 

package/skills/scip-calibrate/SKILL.md

@@ -8,6 +8,7 @@ commands:
   - scip-query dead --json
   - scip-query similar <symbol>
   - scip-query config-validate
+  - scip-query effectiveness --since 30d --json
 ---
 
 # scip-calibrate
@@ -116,9 +117,14 @@ filed upstream.
 
 The finding-outcome ledger keeps calibrating for you: once the repo uses
 diff-gate, per-detector precision is recomputed from real outcomes
-(`detectorPrecision` in `health --json`). Re-run this protocol only after
-major detector upgrades or when the ledger's precision numbers drift from
-what you measured. Write the calibration report to
+(`detectorPrecision` in `health --json`), and the committed event ledger
+makes those outcomes durable and queryable — `scip-query effectiveness
+--since 30d --json` reports per-check caught/same-HEAD-fixed/suppressed/open/
+unverified counts, precision, and median days-to-fix from
+`.scipquery/ledger/events.jsonl`. Run diff-gate before and after the repair,
+before committing, so a changed HEAD cannot be mistaken for a verified fix.
+Re-run this protocol only after major detector upgrades or when the
+ledger's precision numbers drift from what you measured. Write the calibration report to
 `docs/validation/YYYY-MM-DD-external-calibration-<repo>.md` in the shape of
 the exemplars this skill was distilled from — battery table, retro-gate
 walls, per-detector verdicts, noise archetypes, caps and deviations.

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

@@ -6,6 +6,8 @@ commands:
     when: "Target and harness: baseline timings for a scip-query command target."
   - template: "scip-query bench --json --cold-index --include-heavy --timeout-ms 600000"
     when: "Target and harness: cold-path and heavy-detector timings."
+  - template: "scip-query work-audit <profile> --json"
+    when: "Profile the chain: rank exact repeated computations by measured avoidable time."
   - template: "scip-query plan-context <entry-symbol-or-file>"
     when: "Trace behavior: pre-edit context for the profiled entry point."
   - template: "scip-query call-graph <entry-symbol>"
@@ -40,6 +42,7 @@ One sentence to decide: if you can already name the one function you expect to f
 | --- | --- | --- |
 | `scip-query bench --json` | Benchmark indexing and command runtimes for this repository | Target and harness: baseline timings for a scip-query command target. |
 | `scip-query bench --json --cold-index --include-heavy --timeout-ms 600000` | Benchmark indexing and command runtimes for this repository | Target and harness: cold-path and heavy-detector timings. |
+| `scip-query work-audit <profile> --json` | Rank exact repeated computations in a profiling JSONL file by measured avoidable time | Profile the chain: rank exact repeated computations by measured avoidable time. |
 | `scip-query plan-context <entry-symbol-or-file>` | Pre-edit planning context for a symbol, file, or module | Trace behavior: pre-edit context for the profiled entry point. |
 | `scip-query call-graph <entry-symbol>` | Show incoming callers and outgoing callees for a symbol | Trace behavior: callers/callees for the pipeline under test. |
 | `scip-query complexity <hot-symbol>` | Per-symbol complexity: branches, cyclomatic estimate, fan-in/out, callees | Diagnose: branches, cyclomatic estimate, fan-in/out for a hot symbol. |
@@ -117,7 +120,7 @@ This step is complete only when each major pipeline step can be timed as a profi
 
 ### 4. Profile the chain
 
-0. Check whether the target app already has an instrumentation layer before adding spans — a bespoke profiling harness competes with the one the codebase already trusts. When the target is scip-query itself, its instrumentation is `src/instrumentation/profile.ts` (`profileSpan`, env-gated by `SCIP_QUERY_PROFILE`/`SCIP_QUERY_PROFILE_OUT`, with `SCIP_QUERY_PROFILE_CACHE_STATE` for cache-state labels) — use it, don't add a parallel one.
+0. Check whether the target app already has an instrumentation layer before adding spans — a bespoke profiling harness competes with the one the codebase already trusts. When the target is scip-query itself, its instrumentation is `src/instrumentation/profile.ts` (`profileSpan`/`profileAsyncSpan`, env-gated by `SCIP_QUERY_PROFILE`/`SCIP_QUERY_PROFILE_OUT`, with `SCIP_QUERY_PROFILE_CACHE_STATE` for cache-state labels and inherited workload/subsystem identities) — use it, don't add a parallel one.
 1. Measure the target unprofiled.
 2. Measure profiled once and compare overhead.
 3. Measure distinct states: cold index, cold evidence/cache fill, warm cache hit, repeated focused run, production-like mixed state.
@@ -125,6 +128,7 @@ This step is complete only when each major pipeline step can be timed as a profi
 5. Split the largest workload-weighted span.
 6. Repeat until the slow operation is a repeated lookup, initialization, scan, traversal, subprocess, serialization step, or wait.
 7. Write span records with cardinality to run history.
+8. When spans carry work identities, run `scip-query work-audit <profile> --json` to separate exact repeats from same-name work on different inputs.
 
 This step is complete only when the dominant cost is concrete enough to form a falsifiable hypothesis.
 

package/skills/scip-query/SKILL.md

@@ -100,7 +100,7 @@ Top commands per routed skill, generated from each skill's own `commands:` front
 | `scip-directory-architecture` | `scip-query system <scope>`, `scip-query locality-candidates --json --full`, `scip-query similar-files --full --json` |
 | `scip-doc-reconcile` | `scip-query doc-drift --json --full`, `scip-query doc-drift <doc>`, `scip-query outline <subject-file>` |
 | `scip-explore` | `scip-query stats`, `scip-query system <module-or-scope>`, `scip-query trace <entry-symbol>` |
-| `scip-hyper-optimization` | `scip-query bench --json`, `scip-query bench --json --cold-index --include-heavy --timeout-ms 600000`, `scip-query plan-context <entry-symbol-or-file>` |
+| `scip-hyper-optimization` | `scip-query bench --json`, `scip-query bench --json --cold-index --include-heavy --timeout-ms 600000`, `scip-query work-audit <profile> --json` |
 | `scip-language-playbook` | `scip-query stats`, `scip-query files <feature-or-module-name>`, `scip-query outline <file>` |
 | `scip-maintainability` | `scip-query stats`, `scip-query system <scope>`, `scip-query surface <scope>` |
 | `scip-probe-reachability` | `scip-query outline <file> --signatures`, `scip-query code <symbol>`, `scip-query trace <symbol>` |